@nan0web/ui-cli 1.0.2 → 1.1.0

package/types/ui/input.d.ts

@@ -1,24 +1,60 @@
+/// <reference types="node" resolution-mode="require"/>
+/** @typedef {import("./select.js").ConsoleLike} ConsoleLike */
+/** @typedef {(input: Input) => Promise<boolean>} LoopFn */
+/** @typedef {(input: Input) => string} NextQuestionFn */
 /**
- * Prompt a question and return the trimmed answer.
+ * Input function.
+ * ---
+ * Must be used only as a type — typedef does not work with full arguments description for functions.
+ * ---
+ * @param {string} question - Prompt displayed to the user.
+ * @param {boolean | LoopFn} [loop=false] - Loop‑control flag, validator or boolean that forces a single answer.
+ * @param {string | NextQuestionFn} [nextQuestion] - When `false` the prompt ends after one answer.
+ *                                            When a `function` is supplied it receives the current {@link Input}
+ *                                            and must return a new question string for the next iteration.
+ *
+ * @returns {Promise<Input>} Resolves with an {@link Input} instance that contains the final answer,
+ *                           the raw value and cancellation state.
+ *
+ * @throws {Error} May propagate errors from the underlying readline interface.
+ */
+export function InputFn(question: string, loop?: boolean | LoopFn | undefined, nextQuestion?: string | NextQuestionFn | undefined): Promise<Input>;
+/**
+ * Low‑level prompt that returns a trimmed string.
+ *
+ * @param {Object} input
+ * @param {string} input.question - Text displayed as a prompt.
+ * @param {string} [input.predef] - Optional predefined answer (useful for testing).
+ * @param {ConsoleLike} [input.console] - Optional console to show predefined value
+ * @param {import("node:readline").Interface} [input.rl] - Readline interface instnace
+ * @returns {Promise<string>} The answer without surrounding whitespace.
  *
- * @param {string} question - Text displayed as a prompt.
- * @returns {Promise<string>} User answer without surrounding whitespace.
+ * When `predef` is supplied the function mimics the usual readline output
+ * (`question + answer + newline`) and returns the trimmed value.
  */
-export function ask(question: string): Promise<string>;
+export function _askRaw(input: {
+    question: string;
+    predef?: string | undefined;
+    console?: import("./select.js").ConsoleLike | undefined;
+    rl?: import("readline").Interface | undefined;
+}): Promise<string>;
 /**
  * Factory that creates a reusable async input handler.
  *
  * @param {string[]} [stops=[]] Words that trigger cancellation.
+ * @param {string|undefined} [predef] Optional predefined answer for testing.
+ * @param {ConsoleLike} [console] Optional console instance.
  * @returns {InputFn} Async function that resolves to an {@link Input}.
  */
-export function createInput(stops?: string[] | undefined): InputFn;
+export function createInput(stops?: string[] | undefined, predef?: string | undefined, console?: import("./select.js").ConsoleLike | undefined): typeof InputFn;
 /**
- * @typedef {Function} InputFn
- * @param {string} question - Prompt displayed to the user.
- * @param {Function|boolean} [loop=false] - Loop control or validator.
- * @param {Function|false} [nextQuestion=false] - Function to compute the next prompt.
- * @returns {Promise<Input>} Resolves with an {@link Input} instance containing the answer.
+ * @param {string[]} predefined
+ * @param {ConsoleLike} console
+ * @param {string[]} [stops=[]]
+ * @returns {import("./select.js").InputFn}
+ * @throws {CancelError}
  */
+export function createPredefinedInput(predefined: string[], console: ConsoleLike, stops?: string[] | undefined): import("./select.js").InputFn;
 /**
  * Represents a line of user input.
  *
@@ -55,5 +91,16 @@ export class Input {
     toString(): string;
     #private;
 }
+/**
+ * High‑level input helper `ask`.
+ *
+ * This constant inherits the full {@link InputFn} signature **and** the
+ * detailed JSDoc description for each argument, as defined in {@link InputFn}.
+ *
+ * @type {InputFn}
+ */
+export const ask: typeof InputFn;
 export default createInput;
-export type InputFn = Function;
+export type ConsoleLike = import("./select.js").ConsoleLike;
+export type LoopFn = (input: Input) => Promise<boolean>;
+export type NextQuestionFn = (input: Input) => string;

package/types/ui/select.d.ts

@@ -1,33 +1,47 @@
+/** @typedef {import("./input.js").Input} Input */
+/** @typedef {import("./input.js").InputFn} InputFn */
+/**
+ * @typedef {Object} ConsoleLike
+ * @property {(...args: any[]) => void} debug
+ * @property {(...args: any[]) => void} log
+ * @property {(...args: any[]) => void} info
+ * @property {(...args: any[]) => void} warn
+ * @property {(...args: any[]) => void} error
+ */
 /**
- * Configuration object for {@link select}.
- *
  * @typedef {Object} SelectConfig
  * @property {string} title – Title displayed above the options list.
  * @property {string} prompt – Prompt displayed for the answer.
  * @property {Array|Map} options – Collection of selectable items.
- * @property {Object} console – Console‑like object with an `info` method.
+ * @property {ConsoleLike} console – Console‑like object with an `info` method.
  * @property {string[]} [stops=[]] Words that trigger cancellation.
- * @property {import("./input.js").InputFn} [ask] Custom ask function (defaults to {@link createInput}).
+ * @property {InputFn} [ask] Custom ask function (defaults to {@link createInput}).
  * @property {string} [invalidPrompt="Invalid choice, try again: "] Message shown on invalid input.
+ */
+/**
+ * Configuration object for {@link select}.
  *
+ * @param {SelectConfig} input
  * @returns {Promise<{index:number,value:any}>} Resolves with the selected index and its value.
+ *
+ * @throws {CancelError} When the user cancels the operation.
+ * @throws {Error} When options are missing or an incorrect value is supplied and no
+ *   `invalidPrompt` is defined.
  */
-export function select({ title, prompt, invalidPrompt, options, console, stops, ask: initAsk, }: {
-    title: any;
-    prompt: any;
-    invalidPrompt?: string | undefined;
-    options: any;
-    console: any;
-    stops?: any[] | undefined;
-    ask: any;
-}): Promise<{
+export function select(input: SelectConfig): Promise<{
     index: number;
     value: any;
 }>;
 export default select;
-/**
- * Configuration object for {@link select }.
- */
+export type Input = import("./input.js").Input;
+export type InputFn = typeof import("./input.js").InputFn;
+export type ConsoleLike = {
+    debug: (...args: any[]) => void;
+    log: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
 export type SelectConfig = {
     /**
      * – Title displayed above the options list.
@@ -44,7 +58,7 @@ export type SelectConfig = {
     /**
      * – Console‑like object with an `info` method.
      */
-    console: any;
+    console: ConsoleLike;
     /**
      * Words that trigger cancellation.
      */
@@ -52,7 +66,7 @@ export type SelectConfig = {
     /**
      * Custom ask function (defaults to {@link createInput }).
      */
-    ask?: Function | undefined;
+    ask?: typeof import("./input.js").InputFn | undefined;
     /**
      * Message shown on invalid input.
      */