@decaf-ts/utils 1.2.2 → 1.3.0

package/lib/types/utils/types.d.ts

@@ -1,112 +0,0 @@
-import { ChildProcessWithoutNullStreams } from "child_process";
-import { Environment } from "@decaf-ts/logging";
-/**
- * @description Defines the structure for promise resolution and rejection.
- * @summary Provides methods to resolve or reject a promise.
- * @template R - The type of the resolved value.
- * @template E - The type of the error value, defaulting to Error.
- * @typedef {Object} PromiseExecutor
- * @property {function(R): void} resolve - Function to resolve the promise.
- * @property {function(E): void} reject - Function to reject the promise.
- * @memberOf module:utils
- */
-export interface PromiseExecutor<R, E = Error> {
-    resolve: (value: R | PromiseLike<R>) => void;
-    reject: (error: E) => void;
-}
-/**
- * @description Represents the result of a command execution.
- * @summary Extends Promise with additional properties related to the command execution.
- * This interface provides a comprehensive way to handle and interact with the results
- * of an asynchronous command execution, including access to the command details,
- * output logs, and the ability to abort the execution.
- *
- * @template R - The type of the resolved value, defaulting to void.
- * @interface CommandResult
- * @extends Promise<R>
- * @memberOf module:utils
- */
-export interface CommandResult<R = void> {
-    promise: Promise<R>;
-    /**
-     * @description Controller to abort the command execution.
-     * @summary Provides a mechanism to cancel the ongoing command execution.
-     */
-    abort: AbortController;
-    /**
-     * @description The executed command string.
-     * @summary Contains the actual command that was executed.
-     */
-    command: string;
-    /**
-     * @description The child process object.
-     * @summary Represents the Node.js child process that was spawned to execute the command.
-     */
-    cmd?: ChildProcessWithoutNullStreams;
-    /**
-     * @description Array of stdout logs.
-     * @summary Contains all the standard output messages produced during the command execution.
-     */
-    logs: string[];
-    /**
-     * @description Array of stderr logs.
-     * @summary Contains all the standard error messages produced during the command execution.
-     */
-    errs: string[];
-    /**
-     * @description allows chaining commands.
-     * @summary allows chaining commands (or piping).
-     */
-    pipe: <E>(cb: (r: R) => E) => Promise<E>;
-}
-/**
- * @description Factory type for creating Environment instances.
- * @summary Defines a function type that creates and returns Environment instances.
- *
- * @template T - The type of object the Environment will accumulate.
- * @template E - The specific Environment type to be created, extending Environment<T>.
- * @typedef {function(...unknown[]): E} EnvironmentFactory
- * @memberOf module:utils
- */
-export type EnvironmentFactory<T extends object, E extends Environment<T>> = (...args: unknown[]) => E;
-/**
- * @description Map of project dependencies with detailed information.
- * @summary Represents the structure of project dependencies categorized by type (production, development, peer).
- * Each category contains an array of objects with name and version information.
- *
- * @typedef {Object} DependencyMap
- * @property {Array<{name: string, version: string}>} prod - Production dependencies with name and version.
- * @property {Array<{name: string, version: string}>} dev - Development dependencies with name and version.
- * @property {Array<{name: string, version: string}>} peer - Peer dependencies with name and version.
- * @memberOf module:utils
- */
-export type DependencyMap = {
-    prod: {
-        name: string;
-        version: string;
-    }[];
-    dev: {
-        name: string;
-        version: string;
-    }[];
-    peer: {
-        name: string;
-        version: string;
-    }[];
-};
-/**
- * @description Simplified map of project dependencies.
- * @summary Represents a simplified structure of project dependencies categorized by type.
- * Each category contains an optional array of dependency names without version information.
- *
- * @typedef {Object} SimpleDependencyMap
- * @property {string[]} [prod] - Optional array of production dependency names.
- * @property {string[]} [dev] - Optional array of development dependency names.
- * @property {string[]} [peer] - Optional array of peer dependency names.
- * @memberOf module:utils
- */
-export type SimpleDependencyMap = {
-    prod?: string[];
-    dev?: string[];
-    peer?: string[];
-};

package/lib/types/utils/utils.d.ts

@@ -1,133 +0,0 @@
-import { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "child_process";
-import { StandardOutputWriter } from "../writers/StandardOutputWriter";
-import { CommandResult } from "./types";
-import { OutputWriterConstructor } from "../writers/types";
-import { Logger } from "@decaf-ts/logging";
-/**
- * @description Creates a locked version of a function.
- * @summary This higher-order function takes a function and returns a new function that ensures
- * sequential execution of the original function, even when called multiple times concurrently.
- * It uses a Promise-based locking mechanism to queue function calls.
- *
- * @template R - The return type of the input function.
- *
- * @param f - The function to be locked. It can take any number of parameters and return a value of type R.
- * @return A new function with the same signature as the input function, but with sequential execution guaranteed.
- *
- * @function lockify
- *
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant LockedFunction
- *   participant OriginalFunction
- *   Caller->>LockedFunction: Call with params
- *   LockedFunction->>LockedFunction: Check current lock
- *   alt Lock is resolved
- *     LockedFunction->>OriginalFunction: Execute with params
- *     OriginalFunction-->>LockedFunction: Return result
- *     LockedFunction-->>Caller: Return result
- *   else Lock is pending
- *     LockedFunction->>LockedFunction: Queue execution
- *     LockedFunction-->>Caller: Return promise
- *     Note over LockedFunction: Wait for previous execution
- *     LockedFunction->>OriginalFunction: Execute with params
- *     OriginalFunction-->>LockedFunction: Return result
- *     LockedFunction-->>Caller: Resolve promise with result
- *   end
- *   LockedFunction->>LockedFunction: Update lock
- *
- * @memberOf module:utils
- */
-export declare function lockify<R>(f: (...params: unknown[]) => R): (...params: unknown[]) => Promise<R>;
-/**
- * @description Chains multiple abort signals to a controller.
- * @summary Creates a mechanism where multiple abort signals can trigger a single abort controller.
- * This is useful for coordinating cancellation across multiple asynchronous operations.
- *
- * @param {AbortController} controller - The abort controller to be triggered by signals.
- * @param {...AbortSignal} signals - One or more abort signals that can trigger the controller.
- * @return {AbortController} The input controller, now connected to the signals.
- *
- * @function chainAbortController
- *
- * @memberOf module:utils
- */
-export declare function chainAbortController(controller: AbortController, ...signals: AbortSignal[]): AbortController;
-/**
- * @description Creates a new controller chained to multiple abort signals.
- * @summary Creates a new abort controller that will be triggered if any of the provided signals are aborted.
- *
- * @param {...AbortSignal} signals - One or more abort signals that can trigger the new controller.
- * @return {AbortController} A new abort controller connected to the signals.
- *
- * @function chainAbortController
- *
- * @memberOf module:utils
- */
-export declare function chainAbortController(...signals: AbortSignal[]): AbortController;
-/**
- * @description Spawns a command as a child process with output handling.
- * @summary Creates a child process to execute a command with support for piping multiple commands,
- * custom output handling, and abort control. This function handles the low-level details of
- * spawning processes and connecting their inputs/outputs when piping is used.
- *
- * @template R - The type of the processed output, defaulting to string.
- * @param {StandardOutputWriter<R>} output - The output writer to handle command output.
- * @param {string} command - The command to execute, can include pipe operators.
- * @param {SpawnOptionsWithoutStdio} opts - Options for the spawned process.
- * @param {AbortController} abort - Controller to abort the command execution.
- * @param {Logger} logger - Logger for recording command execution details.
- * @return {ChildProcessWithoutNullStreams} The spawned child process.
- *
- * @function spawnCommand
- *
- * @memberOf module:utils
- */
-export declare function spawnCommand<R = string>(output: StandardOutputWriter<R>, command: string, opts: SpawnOptionsWithoutStdio, abort: AbortController, logger: Logger): ChildProcessWithoutNullStreams;
-/**
- * @description Executes a command asynchronously with customizable output handling.
- * @summary This function runs a shell command as a child process, providing fine-grained
- * control over its execution and output handling. It supports custom output writers,
- * allows for command abortion, and captures both stdout and stderr.
- *
- * @template R - The type of the resolved value from the command execution.
- *
- * @param command - The command to run, either as a string or an array of strings.
- * @param opts - Spawn options for the child process. Defaults to an empty object.
- * @param outputConstructor - Constructor for the output writer. Defaults to StandardOutputWriter.
- * @param args - Additional arguments to pass to the output constructor.
- * @return {CommandResult} A promise that resolves to the command result of type R.
- *
- * @function runCommand
- *
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant runCommand
- *   participant OutputWriter
- *   participant ChildProcess
- *   Caller->>runCommand: Call with command and options
- *   runCommand->>OutputWriter: Create new instance
- *   runCommand->>OutputWriter: Parse command
- *   runCommand->>ChildProcess: Spawn process
- *   ChildProcess-->>runCommand: Return process object
- *   runCommand->>ChildProcess: Set up event listeners
- *   loop For each stdout data
- *     ChildProcess->>runCommand: Emit stdout data
- *     runCommand->>OutputWriter: Handle stdout data
- *   end
- *   loop For each stderr data
- *     ChildProcess->>runCommand: Emit stderr data
- *     runCommand->>OutputWriter: Handle stderr data
- *   end
- *   ChildProcess->>runCommand: Emit error (if any)
- *   runCommand->>OutputWriter: Handle error
- *   ChildProcess->>runCommand: Emit exit
- *   runCommand->>OutputWriter: Handle exit
- *   OutputWriter-->>runCommand: Resolve or reject promise
- *   runCommand-->>Caller: Return CommandResult
- *
- * @memberOf module:utils
- */
-export declare function runCommand<R = string>(command: string, opts?: SpawnOptionsWithoutStdio, outputConstructor?: OutputWriterConstructor<R, StandardOutputWriter<R>, Error>, ...args: unknown[]): CommandResult<R>;

package/lib/types/writers/OutputWriter.d.ts

@@ -1,49 +0,0 @@
-/**
- * @description Defines the structure for output writing operations.
- * @summary The OutputWriter interface provides a standardized set of methods for handling
- * various types of output in a command-line interface (CLI) application. It includes
- * methods for writing data, handling errors, and managing the program's exit process.
- * This interface allows for consistent output handling across different parts of the application.
- *
- * @interface OutputWriter
- * @memberOf module:utils
- */
-export interface OutputWriter {
-    /**
-     * @description Handles the output of data chunks.
-     * @summary Processes and writes a chunk of data to the output stream.
-     * This method is typically used for standard output operations.
-     *
-     * @param chunk - The data to be written. Can be of any type.
-     * @return void
-     */
-    data(chunk: any): void;
-    /**
-     * @description Handles error output.
-     * @summary Processes and writes error information to the error output stream.
-     * This method is used for non-critical errors or warnings.
-     *
-     * @param chunk - The error data to be written. Can be of any type.
-     * @return void
-     */
-    error(chunk: any): void;
-    /**
-     * @description Handles critical errors.
-     * @summary Processes and writes critical error information.
-     * This method is used for handling and reporting Error objects.
-     *
-     * @param err - The Error object to be processed and written.
-     * @return void
-     */
-    errors(err: Error): void;
-    /**
-     * @description Manages the program exit process.
-     * @summary Handles the termination of the program with a specified exit code.
-     * This method is called when the program needs to exit, either successfully or due to an error.
-     *
-     * @param code - The exit code to be used when terminating the program.
-     * @param logs - Array of log messages to be processed before exiting.
-     * @return void
-     */
-    exit(code: number, logs: string[]): void;
-}

package/lib/types/writers/RegexpOutputWriter.d.ts

@@ -1,110 +0,0 @@
-import { StandardOutputWriter } from "./StandardOutputWriter";
-import { PromiseExecutor } from "../utils/types";
-/**
- * @description A specialized output writer that uses regular expressions to process output.
- * @summary This class extends StandardOutputWriter to provide regex-based output processing.
- * It allows for pattern matching in the output stream and can trigger specific actions
- * based on matched patterns.
- *
- * @template T - 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 regexp - A string or RegExp to match against the output.
- * @param flags - Optional flags for the RegExp constructor, defaults to "g".
- *
- * @class
- * @example
- * ```typescript
- * import { RegexpOutputWriter } from '@decaf-ts/utils';
- * import { PromiseExecutor } from '@decaf-ts/utils';
- *
- * // Create a promise executor
- * const executor: PromiseExecutor<string, Error> = {
- *   resolve: (value) => console.log(`Resolved: ${value}`),
- *   reject: (error) => console.error(`Rejected: ${error.message}`)
- * };
- *
- * // Create a regexp output writer that matches version numbers
- * const writer = new RegexpOutputWriter('node --version', executor, /v(\d+\.\d+\.\d+)/);
- *
- * // Use the writer to handle command output
- * writer.data('v14.17.0');  // This will automatically resolve with "v14.17.0"
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant Client
- *   participant RegexpOutputWriter
- *   participant StandardOutputWriter
- *   participant Logger
- *
- *   Client->>RegexpOutputWriter: new RegexpOutputWriter(cmd, lock, regexp, flags)
- *   RegexpOutputWriter->>StandardOutputWriter: super(cmd, lock)
- *   StandardOutputWriter->>Logger: Logging.for(cmd)
- *   RegexpOutputWriter->>RegexpOutputWriter: compile regexp
- *
- *   Client->>RegexpOutputWriter: data(chunk)
- *   RegexpOutputWriter->>StandardOutputWriter: super.data(chunk)
- *   StandardOutputWriter->>Logger: logger.info(log)
- *   RegexpOutputWriter->>RegexpOutputWriter: testAndResolve(chunk)
- *   RegexpOutputWriter->>RegexpOutputWriter: test(chunk)
- *   alt match found
- *     RegexpOutputWriter->>RegexpOutputWriter: resolve(match[0])
- *     RegexpOutputWriter->>StandardOutputWriter: resolve(match[0])
- *   end
- *
- *   Client->>RegexpOutputWriter: error(chunk)
- *   RegexpOutputWriter->>StandardOutputWriter: super.error(chunk)
- *   StandardOutputWriter->>Logger: logger.info(log)
- *   RegexpOutputWriter->>RegexpOutputWriter: testAndReject(chunk)
- *   RegexpOutputWriter->>RegexpOutputWriter: test(chunk)
- *   alt match found
- *     RegexpOutputWriter->>RegexpOutputWriter: reject(match[0])
- *     RegexpOutputWriter->>StandardOutputWriter: reject(match[0])
- *   end
- */
-export declare class RegexpOutputWriter extends StandardOutputWriter<string> {
-    /**
-     * @description The regular expression used for matching output.
-     * @summary This readonly property stores the compiled RegExp used for pattern matching.
-     */
-    protected readonly regexp: RegExp;
-    constructor(cmd: string, lock: PromiseExecutor<string, Error>, regexp: string | RegExp, flags?: string);
-    /**
-     * @description Tests the input data against the stored regular expression.
-     * @summary Executes the regular expression on the input data and returns the match result.
-     *
-     * @param data - The string to test against the regular expression.
-     * @return The result of the regular expression execution, or undefined if an error occurs.
-     */
-    private test;
-    /**
-     * @description Tests the data and resolves the promise if a match is found.
-     * @summary Executes the test method and resolves the promise with the first match group if successful.
-     *
-     * @param data - The string to test against the regular expression.
-     */
-    protected testAndResolve(data: string): void;
-    /**
-     * @description Tests the data and rejects the promise if a match is found.
-     * @summary Executes the test method and rejects the promise with the first match group if successful.
-     *
-     * @param data - The string to test against the regular expression.
-     */
-    protected testAndReject(data: string): void;
-    /**
-     * @description Processes incoming data chunks.
-     * @summary Calls the parent class data method and then tests the data for a match to potentially resolve the promise.
-     *
-     * @param chunk - The data chunk to process.
-     */
-    data(chunk: any): void;
-    /**
-     * @description Processes incoming error chunks.
-     * @summary Calls the parent class error method and then tests the data for a match to potentially reject the promise.
-     *
-     * @param chunk - The error chunk to process.
-     */
-    error(chunk: any): void;
-}

package/lib/types/writers/StandardOutputWriter.d.ts

@@ -1,130 +0,0 @@
-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;
-}

package/lib/types/writers/index.d.ts

@@ -1,4 +0,0 @@
-export * from './OutputWriter';
-export * from './RegexpOutputWriter';
-export * from './StandardOutputWriter';
-export * from './types';

package/lib/types/writers/types.d.ts

@@ -1,29 +0,0 @@
-import { StandardOutputWriter } from "./StandardOutputWriter";
-import { PromiseExecutor } from "../utils/types";
-/**
- * @description Represents the type of output stream.
- * @summary A union type for standard output and standard error streams.
- * @typedef {("stdout" | "stderr")} OutputType
- * @memberOf module:utils
- */
-export type OutputType = "stdout" | "stderr";
-/**
- * @description Constructor type for output writers.
- * @summary Defines the structure for creating new output writer instances. This type represents
- * a constructor function that takes a PromiseExecutor and additional arguments to create
- * a new instance of an output writer. It allows for flexible creation of different types
- * of output writers while maintaining a consistent interface.
- *
- * @template R - The type of the resolved value, defaulting to string.
- * @template C - The type of the output writer, extending StandardOutputWriter<R>.
- * @template E - The type of the error value, defaulting to number.
- *
- * @param {PromiseExecutor<R, E>} lock - The promise executor for managing asynchronous operations.
- * @param {...unknown[]} args - Additional arguments passed to the constructor.
- * @return {C} An instance of the output writer.
- *
- * @memberOf module:utils
- */
-export type OutputWriterConstructor<R = string, C extends StandardOutputWriter<R> = StandardOutputWriter<R>, E = number> = {
-    new (cmd: string, lock: PromiseExecutor<R, E>, ...args: unknown[]): C;
-};