@decaf-ts/utils 0.1.6

package/dist/types/utils/types.d.ts

@@ -0,0 +1,81 @@
+import { ChildProcessWithoutNullStreams } from "child_process";
+import { Environment } from "./environment";
+/**
+ * @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 @decaf-ts/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 @decaf-ts/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>;
+}
+export type EnvironmentFactory<T extends object, E extends Environment<T>> = (...args: unknown[]) => E;
+export type DependencyMap = {
+    prod: {
+        name: string;
+        version: string;
+    }[];
+    dev: {
+        name: string;
+        version: string;
+    }[];
+    peer: {
+        name: string;
+        version: string;
+    }[];
+};
+export type SimpleDependencyMap = {
+    prod?: string[];
+    dev?: string[];
+    peer?: string[];
+};

package/dist/types/utils/utils.d.ts

@@ -0,0 +1,91 @@
+import { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "child_process";
+import { StandardOutputWriter } from "../writers/StandardOutputWriter";
+import { CommandResult } from "./types";
+import { OutputWriterConstructor } from "../writers/types";
+import { VerbosityLogger } from "../output/types";
+/**
+ * @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 @decaf-ts/utils
+ */
+export declare function lockify<R>(f: (...params: unknown[]) => R): (...params: unknown[]) => Promise<R>;
+export declare function chainAbortController(controller: AbortController, ...signals: AbortSignal[]): AbortController;
+export declare function chainAbortController(...signals: AbortSignal[]): AbortController;
+export declare function spawnCommand<R = string>(output: StandardOutputWriter<R>, command: string, opts: SpawnOptionsWithoutStdio, abort: AbortController, logger: VerbosityLogger): 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 @decaf-ts/utils
+ */
+export declare function runCommand<R = string>(command: string, opts?: SpawnOptionsWithoutStdio, outputConstructor?: OutputWriterConstructor<R, StandardOutputWriter<R>, Error>, ...args: unknown[]): CommandResult<R>;

package/dist/types/utils/web.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @function isBrowser
+ * @description Determines if the current environment is a browser by checking the prototype chain of the global object.
+ * @summary Checks if the code is running in a browser environment.
+ * @returns {boolean} True if the environment is a browser, false otherwise.
+ */
+export declare function isBrowser(): boolean;

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

@@ -0,0 +1,49 @@
+/**
+ * @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 @decaf-ts/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
+     * @return void
+     */
+    exit(code: number, logs: string[]): void;
+}

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

@@ -0,0 +1,69 @@
+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 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.
+ *
+ * @class
+ */
+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;
+    /**
+     * @description Initializes a new instance of RegexpOutputWriter.
+     * @summary Constructs the RegexpOutputWriter with a lock mechanism and a regular expression.
+     *
+     * @param cmd
+     * @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".
+     */
+    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/dist/types/writers/StandardOutputWriter.d.ts

@@ -0,0 +1,91 @@
+import { OutputWriter } from "./OutputWriter";
+import { PromiseExecutor } from "../utils/types";
+import { OutputType } from "./types";
+import { VerbosityLogger } from "../output/types";
+/**
+ * @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 number.
+ *
+ * @param lock - A PromiseExecutor to control the asynchronous flow.
+ * @param args - Additional arguments (unused in the current implementation).
+ *
+ * @class
+ */
+export declare class StandardOutputWriter<R = string> implements OutputWriter {
+    protected cmd: string;
+    protected lock: PromiseExecutor<R>;
+    protected logger: VerbosityLogger;
+    /**
+     * @description Initializes a new instance of StandardOutputWriter.
+     * @summary Constructs the StandardOutputWriter with a lock mechanism and optional arguments.
+     *
+     * @param cmd
+     * @param lock - A PromiseExecutor to control the asynchronous flow.
+     * @param args - Additional arguments (currently unused).
+     */
+    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
+     */
+    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/dist/types/writers/index.d.ts

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

package/dist/types/writers/types.d.ts

@@ -0,0 +1,29 @@
+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 @decaf-ts/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 @decaf-ts/utils
+ */
+export type OutputWriterConstructor<R = string, C extends StandardOutputWriter<R> = StandardOutputWriter<R>, E = number> = {
+    new (cmd: string, lock: PromiseExecutor<R, E>, ...args: unknown[]): C;
+};