@decaf-ts/utils 1.0.10 → 1.2.0

package/lib/types/utils/types.d.cts

@@ -0,0 +1,112 @@
+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/types.d.mts

@@ -0,0 +1,112 @@
+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.cts

@@ -0,0 +1,133 @@
+import { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "child_process";
+import { StandardOutputWriter } from "../writers/StandardOutputWriter.cjs";
+import { CommandResult } from "./types.cjs";
+import { OutputWriterConstructor } from "../writers/types.cjs";
+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/utils/utils.d.mts

@@ -0,0 +1,133 @@
+import { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "child_process";
+import { StandardOutputWriter } from "../writers/StandardOutputWriter.js";
+import { CommandResult } from "./types.js";
+import { OutputWriterConstructor } from "../writers/types.js";
+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.cts

@@ -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 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/OutputWriter.d.mts

@@ -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 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;
+}