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

module management utils for decaf-ts

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>;