@decaf-ts/utils 0.1.6

package/dist/types/input/input.d.ts

@@ -0,0 +1,472 @@
+import prompts, { Choice, Falsy, InitialReturnValue, PrevCaller, PromptObject, PromptType, ValueOrFunc } from "prompts";
+import { Writable, Readable } from "stream";
+import { Kleur } from "../output/types";
+import { ParseArgsOptionsConfig, ParseArgsResult } from "./types";
+/**
+ * @description Represents a user input prompt with various configuration options.
+ * @summary This class provides a flexible interface for creating and managing user input prompts.
+ * It implements the PromptObject interface from the 'prompts' library and offers methods to set
+ * various properties of the prompt. The class also includes static methods for common input scenarios
+ * and argument parsing.
+ *
+ * @template R - The type of the prompt name, extending string.
+ *
+ * @param name - The name of the prompt, used as the key in the returned answers object.
+ *
+ * @class
+ */
+export declare class UserInput<R extends string = string> implements PromptObject<R> {
+    private static readonly logger;
+    /**
+     * @description The type of the prompt.
+     * @summary Determines the input method (e.g., text, number, confirm).
+     */
+    type: PromptType | Falsy | PrevCaller<R, PromptType | Falsy>;
+    /**
+     * @description The name of the prompt.
+     * @summary Used as the key in the returned answers object.
+     */
+    name: ValueOrFunc<R>;
+    /**
+     * @description The message displayed to the user.
+     * @summary The question or instruction presented to the user.
+     */
+    message?: ValueOrFunc<string> | undefined;
+    /**
+     * @description The initial value of the prompt.
+     * @summary The default value presented to the user.
+     */
+    initial?: InitialReturnValue | PrevCaller<R, InitialReturnValue | Promise<InitialReturnValue>> | undefined;
+    /**
+     * @description The style of the prompt.
+     * @summary Determines the visual style of the prompt.
+     */
+    style?: string | PrevCaller<R, string | Falsy> | undefined;
+    /**
+     * @description The format function for the input.
+     * @summary A function to format the user's input before it's returned.
+     */
+    format?: PrevCaller<R, void> | undefined;
+    /**
+     * @description The validation function for the input.
+     * @summary A function to validate the user's input.
+     */
+    validate?: PrevCaller<R, boolean | string | Promise<boolean | string>> | undefined;
+    /**
+     * @description The onState callback function.
+     * @summary A function called when the state of the prompt changes.
+     */
+    onState?: PrevCaller<R, void> | undefined;
+    onRender?: ((kleur: Kleur) => void) | undefined;
+    /**
+     * @description The minimum value for number inputs.
+     * @summary The lowest number the user can input.
+     */
+    min?: number | PrevCaller<R, number | Falsy> | undefined;
+    /**
+     * @description The maximum value for number inputs.
+     * @summary The highest number the user can input.
+     */
+    max?: number | PrevCaller<R, number | Falsy> | undefined;
+    /**
+     * @description Whether to allow float values for number inputs.
+     * @summary If true, allows decimal numbers.
+     */
+    float?: boolean | PrevCaller<R, boolean | Falsy> | undefined;
+    /**
+     * @description The number of decimal places to round to for float inputs.
+     * @summary Determines the precision of float inputs.
+     */
+    round?: number | PrevCaller<R, number | Falsy> | undefined;
+    /**
+     * @description Instructions for the user.
+     * @summary Additional guidance provided to the user.
+     */
+    instructions?: string | boolean | undefined;
+    /**
+     * @description The increment value for number inputs.
+     * @summary The step size when increasing or decreasing the number.
+     */
+    increment?: number | PrevCaller<R, number | Falsy> | undefined;
+    /**
+     * @description The separator for list inputs.
+     * @summary The character used to separate list items.
+     */
+    separator?: string | PrevCaller<R, string | Falsy> | undefined;
+    /**
+     * @description The active option style for select inputs.
+     * @summary The style applied to the currently selected option.
+     */
+    active?: string | PrevCaller<R, string | Falsy> | undefined;
+    /**
+     * @description The inactive option style for select inputs.
+     * @summary The style applied to non-selected options.
+     */
+    inactive?: string | PrevCaller<R, string | Falsy> | undefined;
+    choices?: Choice[] | PrevCaller<R, Choice[] | Falsy> | undefined;
+    /**
+     * @description The hint text for the prompt.
+     * @summary Additional information displayed to the user.
+     */
+    hint?: string | PrevCaller<R, string | Falsy> | undefined;
+    /**
+     * @description The warning text for the prompt.
+     * @summary A warning message displayed to the user.
+     */
+    warn?: string | PrevCaller<R, string | Falsy> | undefined;
+    suggest?: ((input: any, choices: Choice[]) => Promise<any>) | undefined;
+    /**
+     * @description The limit for list inputs.
+     * @summary The maximum number of items that can be selected.
+     */
+    limit?: number | PrevCaller<R, number | Falsy> | undefined;
+    /**
+     * @description The mask for password inputs.
+     * @summary The character used to hide the user's input.
+     */
+    mask?: string | PrevCaller<R, string | Falsy> | undefined;
+    /**
+     * @description The stdout stream for the prompt.
+     * @summary The output stream used by the prompt.
+     */
+    stdout?: Writable | undefined;
+    /**
+     * @description The stdin stream for the prompt.
+     * @summary The input stream used by the prompt.
+     */
+    stdin?: Readable | undefined;
+    /**
+     * @description Creates a new UserInput instance.
+     * @summary Initializes a new UserInput object with the given name.
+     *
+     * @param name - The name of the prompt.
+     */
+    constructor(name: ValueOrFunc<R>);
+    /**
+     * @description Sets the type of the prompt.
+     * @summary Configures the input method for the prompt.
+     *
+     * @param type - The type of the prompt.
+     * @returns This UserInput instance for method chaining.
+     */
+    setType(type: PromptType | Falsy | PrevCaller<R, PromptType | Falsy>): this;
+    /**
+     * @description Sets the message of the prompt.
+     * @summary Configures the question or instruction presented to the user.
+     *
+     * @param value - The message to be displayed.
+     * @returns This UserInput instance for method chaining.
+     */
+    setMessage(value: ValueOrFunc<string> | undefined): this;
+    /**
+     * @description Sets the initial value of the prompt.
+     * @summary Configures the default value presented to the user.
+     *
+     * @param value - The initial value.
+     * @returns This UserInput instance for method chaining.
+     */
+    setInitial(value: InitialReturnValue | PrevCaller<R, InitialReturnValue | Promise<InitialReturnValue>> | undefined): this;
+    /**
+     * @description Sets the style of the prompt.
+     * @summary Configures the visual style of the prompt.
+     *
+     * @param value - The style to be applied.
+     * @returns This UserInput instance for method chaining.
+     */
+    setStyle(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    /**
+     * @description Sets the format function of the prompt.
+     * @summary Configures a function to format the user's input before it's returned.
+     *
+     * @param value - The format function.
+     * @returns This UserInput instance for method chaining.
+     */
+    setFormat(value: PrevCaller<R, void> | undefined): this;
+    /**
+     * @description Sets the validation function of the prompt.
+     * @summary Configures a function to validate the user's input.
+     *
+     * @param value - The validation function.
+     * @returns This UserInput instance for method chaining.
+     */
+    setValidate(value: PrevCaller<R, boolean | string | Promise<boolean | string>> | undefined): this;
+    /**
+     * @description Sets the onState callback of the prompt.
+     * @summary Configures a function to be called when the state of the prompt changes.
+     *
+     * @param value - The onState callback function.
+     * @returns This UserInput instance for method chaining.
+     */
+    setOnState(value: PrevCaller<R, void> | undefined): this;
+    /**
+     * @description Sets the onRender callback of the prompt.
+     * @summary Configures a function to be called when the prompt is rendered.
+     *
+     * @param value - The onRender callback function.
+     * @returns This UserInput instance for method chaining.
+     */
+    setOnRender(value: ((kleur: Kleur) => void) | undefined): this;
+    /**
+     * @description Sets the minimum value for number inputs.
+     * @summary Configures the lowest number the user can input.
+     *
+     * @param value - The minimum value.
+     * @returns This UserInput instance for method chaining.
+     */
+    setMin(value: number | PrevCaller<R, number | Falsy> | undefined): this;
+    /**
+     * @description Sets the maximum value for number inputs.
+     * @summary Configures the highest number the user can input.
+     *
+     * @param value - The maximum value.
+     * @returns This UserInput instance for method chaining.
+     */
+    setMax(value: number | PrevCaller<R, number | Falsy> | undefined): this;
+    /**
+     * @description Sets whether to allow float values for number inputs.
+     * @summary Configures whether decimal numbers are allowed.
+     *
+     * @param value - Whether to allow float values.
+     * @returns This UserInput instance for method chaining.
+     */
+    setFloat(value: boolean | PrevCaller<R, boolean | Falsy> | undefined): this;
+    /**
+     * @description Sets the number of decimal places to round to for float inputs.
+     * @summary Configures the precision of float inputs.
+     *
+     * @param value - The number of decimal places.
+     * @returns This UserInput instance for method chaining.
+     */
+    setRound(value: number | PrevCaller<R, number | Falsy> | undefined): this;
+    /**
+     * @description Sets the instructions for the user.
+     * @summary Configures additional guidance provided to the user.
+     *
+     * @param value - The instructions.
+     * @returns This UserInput instance for method chaining.
+     */
+    setInstructions(value: string | boolean | undefined): this;
+    /**
+     * @description Sets the increment value for number inputs.
+     * @summary Configures the step size when increasing or decreasing the number.
+     *
+     * @param value - The increment value.
+     * @returns This UserInput instance for method chaining.
+     */
+    setIncrement(value: number | PrevCaller<R, number | Falsy> | undefined): this;
+    /**
+     * @description Sets the separator for list inputs.
+     * @summary Configures the character used to separate list items.
+     *
+     * @param value - The separator character.
+     * @returns This UserInput instance for method chaining.
+     */
+    setSeparator(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    /**
+     * @description Sets the active option style for select inputs.
+     * @summary Configures the style applied to the currently selected option.
+     *
+     * @param value - The active option style.
+     * @returns This UserInput instance for method chaining.
+     */
+    setActive(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    /**
+     * @description Sets the inactive option style for select inputs.
+     * @summary Configures the style applied to non-selected options.
+     *
+     * @param value - The inactive option style.
+     * @returns This UserInput instance for method chaining.
+     */
+    setInactive(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    setChoices(value: Choice[] | PrevCaller<R, Choice[] | Falsy> | undefined): this;
+    /**
+     * @description Sets the hint text for the prompt.
+     * @summary Configures additional information displayed to the user.
+     *
+     * @param value - The hint text.
+     * @returns This UserInput instance for method chaining.
+     */
+    setHint(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    /**
+     * @description Sets the warning text for the prompt.
+     * @summary Configures a warning message displayed to the user.
+     *
+     * @param value - The warning text.
+     * @returns This UserInput instance for method chaining.
+     */
+    setWarn(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    setSuggest(value: ((input: any, choices: Choice[]) => Promise<any>) | undefined): this;
+    /**
+     * @description Sets the limit for list inputs.
+     * @summary Configures the maximum number of items that can be selected in list-type prompts.
+     * @template R - The type of the prompt name, extending string.
+     * @param value - The maximum number of items that can be selected, or a function to determine this value.
+     * @return This UserInput instance for method chaining.
+     */
+    setLimit(value: number | PrevCaller<R, number | Falsy> | undefined): this;
+    /**
+     * @description Sets the mask for password inputs.
+     * @summary Configures the character used to hide the user's input in password-type prompts.
+     * @template R - The type of the prompt name, extending string.
+     * @param value - The character used to mask the input, or a function to determine this value.
+     * @return This UserInput instance for method chaining.
+     */
+    setMask(value: string | PrevCaller<R, string | Falsy> | undefined): this;
+    /**
+     * @description Sets the stdout stream for the prompt.
+     * @summary Configures the output stream used by the prompt for displaying messages and results.
+     * @param value - The Writable stream to be used as stdout.
+     * @return This UserInput instance for method chaining.
+     */
+    setStdout(value: Writable | undefined): this;
+    /**
+     * @description Sets the stdin stream for the prompt.
+     * @summary Configures the input stream used by the prompt for receiving user input.
+     * @param value - The Readable stream to be used as stdin.
+     * @return This UserInput instance for method chaining.
+     */
+    setStdin(value: Readable | undefined): this;
+    /**
+     * @description Asks the user for input based on the current UserInput configuration.
+     * @summary Prompts the user and returns their response as a single value.
+     * @template R - The type of the prompt name, extending string.
+     * @return A Promise that resolves to the user's answer.
+     */
+    ask(): Promise<prompts.Answers<R>[R]>;
+    /**
+     * @description Asks the user one or more questions based on the provided UserInput configurations.
+     * @summary Prompts the user with one or more questions and returns their answers as an object.
+     * @template R - The type of the prompt name, extending string.
+     * @param question - A single UserInput instance or an array of UserInput instances.
+     * @return A Promise that resolves to an object containing the user's answers.
+     * @mermaid
+     * sequenceDiagram
+     *   participant U as User
+     *   participant A as ask method
+     *   participant P as prompts library
+     *   A->>P: Call prompts with question(s)
+     *   P->>U: Display prompt(s)
+     *   U->>P: Provide input
+     *   P->>A: Return answers
+     *   A->>A: Process answers
+     *   A-->>Caller: Return processed answers
+     */
+    static ask<R extends string = string>(question: UserInput<R> | UserInput<R>[]): Promise<prompts.Answers<R>>;
+    /**
+     * @description Asks the user for a number input.
+     * @summary Prompts the user to enter a number, with optional minimum, maximum, and initial values.
+     * @param name - The name of the prompt, used as the key in the returned answers object.
+     * @param question - The message displayed to the user.
+     * @param min - The minimum allowed value (optional).
+     * @param max - The maximum allowed value (optional).
+     * @param initial - The initial value presented to the user (optional).
+     * @return A Promise that resolves to the number entered by the user.
+     */
+    static askNumber(name: string, question: string, min?: number, max?: number, initial?: number): Promise<number>;
+    /**
+     * @description Asks the user for a text input.
+     * @summary Prompts the user to enter text, with optional masking and initial value.
+     * @param name - The name of the prompt, used as the key in the returned answers object.
+     * @param question - The message displayed to the user.
+     * @param mask - The character used to mask the input (optional, for password-like inputs).
+     * @param initial - The initial value presented to the user (optional).
+     * @return A Promise that resolves to the text entered by the user.
+     */
+    static askText(name: string, question: string, mask?: string | undefined, initial?: string): Promise<string>;
+    /**
+     * @description Asks the user for a confirmation (yes/no).
+     * @summary Prompts the user with a yes/no question and returns a boolean result.
+     * @param name - The name of the prompt, used as the key in the returned answers object.
+     * @param question - The message displayed to the user.
+     * @param initial - The initial value presented to the user (optional).
+     * @return A Promise that resolves to a boolean representing the user's answer.
+     */
+    static askConfirmation(name: string, question: string, initial?: boolean): Promise<boolean>;
+    /**
+     * @description Repeatedly asks for input until a valid response is given or the limit is reached.
+     * @summary This method insists on getting a valid input from the user, allowing for a specified number of attempts.
+     *
+     * @template R - The type of the expected result.
+     * @param input - The UserInput instance to use for prompting.
+     * @param test - A function to validate the user's input.
+     * @param limit - The maximum number of attempts allowed (default is 1).
+     * @param defaultConfirmation
+     * @return A Promise that resolves to the valid input or undefined if the limit is reached.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant U as User
+     *   participant I as insist method
+     *   participant A as ask method
+     *   participant T as test function
+     *   participant C as askConfirmation method
+     *   loop Until valid input or limit reached
+     *     I->>A: Call ask with input
+     *     A->>U: Prompt user
+     *     U->>A: Provide input
+     *     A->>I: Return result
+     *     I->>T: Test result
+     *     alt Test passes
+     *       I->>C: Ask for confirmation
+     *       C->>U: Confirm input
+     *       U->>C: Provide confirmation
+     *       C->>I: Return confirmation
+     *       alt Confirmed
+     *         I-->>Caller: Return valid result
+     *       else Not confirmed
+     *         I->>I: Continue loop
+     *       end
+     *     else Test fails
+     *       I->>I: Continue loop
+     *     end
+     *   end
+     *   I-->>Caller: Return undefined if limit reached
+     */
+    static insist<R>(input: UserInput, test: (res: string | number) => boolean, defaultConfirmation: boolean, limit?: number): Promise<R | undefined>;
+    /**
+     * @description Repeatedly asks for text input until a valid response is given or the limit is reached.
+     * @summary This method insists on getting a valid text input from the user, allowing for a specified number of attempts.
+     *
+     * @param name - The name of the prompt, used as the key in the returned answers object.
+     * @param question - The message displayed to the user.
+     * @param test - A function to validate the user's input.
+     * @param mask - The character used to mask the input (optional, for password-like inputs).
+     * @param initial - The initial value presented to the user (optional).
+     * @param defaultConfirmation
+     * @param limit - The maximum number of attempts allowed (default is -1, meaning unlimited).
+     * @return A Promise that resolves to the valid input or undefined if the limit is reached.
+     */
+    static insistForText(name: string, question: string, test: (res: string) => boolean, mask?: string | undefined, initial?: string, defaultConfirmation?: boolean, limit?: number): Promise<string>;
+    /**
+     * @description Repeatedly asks for number input until a valid response is given or the limit is reached.
+     * @summary This method insists on getting a valid number input from the user, allowing for a specified number of attempts.
+     *
+     * @param name - The name of the prompt, used as the key in the returned answers object.
+     * @param question - The message displayed to the user.
+     * @param test - A function to validate the user's input.
+     * @param min - The minimum allowed value (optional).
+     * @param max - The maximum allowed value (optional).
+     * @param initial - The initial value presented to the user (optional).
+     * @param defaultConfirmation
+     * @param limit - The maximum number of attempts allowed (default is -1, meaning unlimited).
+     * @return A Promise that resolves to the valid input or undefined if the limit is reached.
+     */
+    static insistForNumber(name: string, question: string, test: (res: number) => boolean, min?: number, max?: number, initial?: number, defaultConfirmation?: boolean, limit?: number): Promise<number>;
+    /**
+     * @description Parses command-line arguments based on the provided options.
+     * @summary Uses Node.js's util.parseArgs to parse command-line arguments and return the result.
+     * @param options - Configuration options for parsing arguments.
+     * @return An object containing the parsed arguments.
+     * @mermaid
+     * sequenceDiagram
+     *   participant C as Caller
+     *   participant P as parseArgs method
+     *   participant U as util.parseArgs
+     *   C->>P: Call with options
+     *   P->>P: Prepare args object
+     *   P->>U: Call parseArgs with prepared args
+     *   U->>P: Return parsed result
+     *   P-->>C: Return ParseArgsResult
+     */
+    static parseArgs(options: ParseArgsOptionsConfig): ParseArgsResult;
+}

package/dist/types/input/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @description Configuration for a single command-line argument option.
+ * @summary Defines the structure and behavior of a command-line option.
+ * @interface ParseArgsOptionConfig
+ * @property {("string" | "boolean")} type - The data type of the option.
+ * @property {boolean} [multiple] - Whether the option can be specified multiple times.
+ * @property {string} [short] - The short (single-character) alias for the option.
+ * @property {string | boolean | string[] | boolean[]} [default] - The default value(s) for the option.
+ * @memberOf @decaf-ts/utils
+ */
+export interface ParseArgsOptionConfig {
+    type: "string" | "boolean";
+    multiple?: boolean | undefined;
+    short?: string | undefined;
+    default?: string | boolean | string[] | boolean[] | undefined;
+}
+/**
+ * @description Configuration for all command-line argument options.
+ * @summary A mapping of long option names to their configurations.
+ * @interface ParseArgsOptionsConfig
+ * @memberOf @decaf-ts/utils
+ */
+export interface ParseArgsOptionsConfig {
+    [longOption: string]: ParseArgsOptionConfig;
+}
+/**
+ * @description Represents a parsed command-line option token.
+ * @summary Can be either an option with a value or an option without a value.
+ * @typedef {Object} OptionToken
+ * @memberOf @decaf-ts/utils
+ */
+export type OptionToken = {
+    kind: "option";
+    index: number;
+    name: string;
+    rawName: string;
+    value: string;
+    inlineValue: boolean;
+} | {
+    kind: "option";
+    index: number;
+    name: string;
+    rawName: string;
+    value: undefined;
+    inlineValue: undefined;
+};
+/**
+ * @description Represents a parsed command-line token.
+ * @summary Can be an option, a positional argument, or an option terminator.
+ * @typedef {OptionToken | Object} Token
+ * @memberOf @decaf-ts/utils
+ */
+export type Token = OptionToken | {
+    kind: "positional";
+    index: number;
+    value: string;
+} | {
+    kind: "option-terminator";
+    index: number;
+};
+/**
+ * @description The result of parsing command-line arguments.
+ * @summary Contains parsed values, positional arguments, and optionally the parsed tokens.
+ * @typedef {Object} ParseArgsResult
+ * @property {string | boolean | string[] | boolean[] | undefined} values - Parsed option values.
+ * @property {string[]} positionals - Positional arguments.
+ * @property {Token[]} [tokens] - Parsed tokens (if requested).
+ * @memberOf @decaf-ts/utils
+ */
+export type ParseArgsResult = {
+    values: {
+        [p: string]: string | boolean | (string | boolean)[] | undefined;
+    };
+    positionals: string[];
+    tokens?: Token[];
+};

package/dist/types/output/common.d.ts

@@ -0,0 +1,51 @@
+import { VerbosityLogger } from "./types";
+/**
+ * @description Prints a styled banner to the console.
+ * @summary Generates and prints a colorful ASCII art banner with a random slogan.
+ * @param {VerbosityLogger} [logger] - Optional logger for verbose output.
+ * @function printBanner
+ * @mermaid
+ * sequenceDiagram
+ *   participant printBanner
+ *   participant getSlogan
+ *   participant padEnd
+ *   participant console
+ *   printBanner->>getSlogan: Call getSlogan()
+ *   getSlogan-->>printBanner: Return random slogan
+ *   printBanner->>printBanner: Create banner ASCII art
+ *   printBanner->>printBanner: Split banner into lines
+ *   printBanner->>printBanner: Calculate max line length
+ *   printBanner->>padEnd: Call padEnd with slogan
+ *   padEnd-->>printBanner: Return padded slogan line
+ *   loop For each banner line
+ *     printBanner->>style: Call style(line)
+ *     style-->>printBanner: Return styled line
+ *     printBanner->>console: Log styled line
+ *   end
+ */
+export declare function printBanner(logger?: VerbosityLogger): void;
+/**
+ * @description Retrieves a slogan from the predefined list.
+ * @summary Fetches a random slogan or a specific one by index from the slogans list.
+ * @param {number} [i] - Optional index to retrieve a specific slogan.
+ * @return {string} The selected slogan.
+ * @function getSlogan
+ * @mermaid
+ * sequenceDiagram
+ *   participant getSlogan
+ *   participant Math.random
+ *   participant slogans
+ *   alt i is undefined
+ *     getSlogan->>Math.random: Generate random index
+ *     Math.random-->>getSlogan: Return random index
+ *   else i is defined
+ *     Note over getSlogan: Use provided index
+ *   end
+ *   getSlogan->>slogans: Access slogan at index
+ *   slogans-->>getSlogan: Return slogan
+ *   alt Error occurs
+ *     getSlogan->>getSlogan: Throw error
+ *   end
+ *   getSlogan-->>Caller: Return slogan
+ */
+export declare function getSlogan(i?: number): string;

package/dist/types/output/index.d.ts

@@ -0,0 +1,3 @@
+export * from './common';
+export * from './logging';
+export * from './types';