@topcli/prompts 1.2.0 → 1.3.0

package/README.md

@@ -5,10 +5,10 @@
 [![isc](https://img.shields.io/badge/License-ISC-blue.svg?style=for-the-badge)](https://github.com/TopCli/prompts/blob/main/LICENSE)
 ![build](https://img.shields.io/github/actions/workflow/status/TopCli/prompts/node.js.yml?style=for-the-badge)
 
-Node.js user input library for command-line interfaces.
+Node.js user prompt library for command-line interfaces.
 
 ## Requirements
-- [Node.js](https://nodejs.org/en/) v14 or higher
+- [Node.js](https://nodejs.org/en/) v16 or higher
 
 ## Getting Started
 
@@ -89,38 +89,64 @@ Use `ignoreValues` to skip result render & clear lines after a selected one.
 confirm(message: string, options?: ConfirmOptions): Promise<boolean>
 ```
 
-Boolean prompt, return `options.initial` if user input is different from "y"/"yes"/"n"/"no", (default `false`).
+Boolean prompt, return `options.initial` if user input is different from `y`/`yes`/`n`/`no` (case insensitive), (default `false`).
+
+### `PromptAgent`
+
+The `PromptAgent` class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
+
+```ts
+const agent = PromptAgent.agent();
+agent.nextAnswer("John");
+
+const input = await question("What's your name?");
+assert.equal(input, "John");
+```
+
+> [!WARNING]
+> Answers set with `PromptAgent` will **bypass** any logical & validation rules.
+> Examples:
+> - When using `question()`, `validators` functions will not be executed.
+> - When using `select()`, the answer can be different from the available choices.
+> - When using `confirm()`, the answer can be any type other than boolean.
+> **Use with caution**
 
 ## Interfaces
 
 ```ts
-export interface PromptOptions {
+export interface SharedOptions {
+  stdin?: NodeJS.ReadStream & {
+    fd: 0;
+  };
+  stdout?: NodeJS.WriteStream & {
+    fd: 1;
+  };
+}
+
+export interface Validator {
+  validate: (input: string) => boolean;
+  error: (input?: string) => string;
+}
+
+export interface QuestionOptions extends SharedOptions {
   defaultValue?: string;
-  validators?: {
-    validate: (input: string) => boolean;
-    error: (input: string) => string;
-  }[];
+  validators?: Validator[];
 }
-```
-```ts
+
 export interface Choice {
   value: any;
   label: string;
   description?: string;
 }
-```
 
-```ts
-export interface SelectOptions {
+export interface SelectOptions extends SharedOptions  {
   choices: (Choice | string)[];
-  maxVisible?: number = 8;
+  maxVisible?: number;
   ignoreValues?: (string | number | boolean)[];
 }
-```
 
-```ts
-export interface ConfirmOptions {
-  initial?: boolean = false;
+export interface ConfirmOptions extends SharedOptions  {
+  initial?: boolean;
 }
 ```
 

package/index.d.ts

@@ -1,12 +1,10 @@
-export interface QuestionOptions {
+export interface SharedOptions {
   stdin?: NodeJS.ReadStream & {
     fd: 0;
   };
   stdout?: NodeJS.WriteStream & {
     fd: 1;
   };
-  defaultValue?: string;
-  validators?: Validator[];
 }
 
 export interface Validator {
@@ -14,19 +12,25 @@ export interface Validator {
   error: (input?: string) => string;
 }
 
+export interface QuestionOptions extends SharedOptions {
+  defaultValue?: string;
+  validators?: Validator[];
+}
+
+
 export interface Choice {
   value: any;
   label: string;
   description?: string;
 }
 
-export interface SelectOptions {
+export interface SelectOptions extends SharedOptions  {
   choices: (Choice | string)[];
   maxVisible?: number;
   ignoreValues?: (string | number | boolean)[];
 }
 
-export interface ConfirmOptions {
+export interface ConfirmOptions extends SharedOptions  {
   initial?: boolean;
 }
 
@@ -35,3 +39,29 @@ export function select(message: string, options: SelectOptions): Promise<string>
 export function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
 
 export function required(): Validator;
+
+export class PromptAgent {
+  /**
+   * The prompts answers queue.
+   * When not empty, any prompt will be answered by the first answer in this list.
+   */
+  nextAnswers: Array<string | boolean>;
+
+  static get agent(): PromptAgent;
+
+  /**
+   * Programmatically set the next answer for any prompt (`question()`, `confirm()`, `select()`)
+   *
+   * This is useful for testing.
+   *
+   * @example
+   * ```js
+   * const promptAgent = PromptAgent.agent();
+   * promptAgent.nextAnswer("toto");
+   *
+   * const input = await question("what is your name?");
+   * assert.equal(input, "toto");
+   * ```
+   */
+  nextAnswer(value: string | boolean | Array<string | boolean>): void
+}

package/index.js

@@ -3,6 +3,7 @@ import { ConfirmPrompt } from "./src/confirm-prompt.js";
 import { SelectPrompt } from "./src/select-prompt.js";
 import { QuestionPrompt } from "./src/question-prompt.js";
 import { required } from "./src/validators.js";
+import { PromptAgent } from "./src/prompt-agent.js";
 
 export async function question(message, options = {}) {
   const questionPrompt = new QuestionPrompt(message, options);
@@ -22,4 +23,4 @@ export async function confirm(message, options) {
   return confirmPrompt.confirm();
 }
 
-export { required };
+export { required, PromptAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topcli/prompts",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Node.js user input library for command-line interfaces.",
   "scripts": {
     "test": "node --no-warnings=ExperimentalWarning --loader=esmock --test test/",

package/src/abstract-prompt.js

@@ -5,6 +5,9 @@ import { createInterface } from "node:readline";
 // Import Third-party Dependencies
 import stripAnsi from "strip-ansi";
 
+// Import Internal Dependencies
+import { PromptAgent } from "./prompt-agent.js";
+
 export class AbstractPrompt {
   constructor(message, input = process.stdin, output = process.stdout) {
     if (this.constructor === AbstractPrompt) {
@@ -19,6 +22,7 @@ export class AbstractPrompt {
     this.stdout = output;
     this.message = message;
     this.history = [];
+    this.agent = PromptAgent.agent();
 
     if (this.stdout.isTTY) {
       this.stdin.setRawMode(true);

package/src/confirm-prompt.js

@@ -98,6 +98,15 @@ export class ConfirmPrompt extends AbstractPrompt {
   }
 
   async confirm() {
+    if (this.agent.nextAnswers.length > 0) {
+      const answer = this.agent.nextAnswers.shift();
+      this.selectedValue = answer;
+      this.#onQuestionAnswer();
+      this.destroy();
+
+      return answer;
+    }
+
     this.write(SYMBOLS.HideCursor);
 
     try {

package/src/prompt-agent.js

@@ -0,0 +1,56 @@
+// CONSTANTS
+const kPrivateInstancier = Symbol("instancier");
+
+export class PromptAgent {
+  /**
+   * The prompts answers queue.
+   * When not empty, any prompt will be answered by the first answer in this list.
+   *
+   *  @type {string[]}
+   */
+  nextAnswers = [];
+
+  /**
+   * The shared PromptAgent.
+   *
+   * @type {PromptAgent}
+   */
+  static #this;
+
+  static agent() {
+    // eslint-disable-next-line no-return-assign
+    return this.#this ??= new PromptAgent(kPrivateInstancier);
+  }
+
+  constructor(instancier) {
+    if (instancier !== kPrivateInstancier) {
+      throw new Error("Cannot instanciate PromptAgent, use PromptAgent.agent() instead");
+    }
+  }
+
+  /**
+   * Programmatically set the next answer for any prompt (`question()`, `confirm()`, `select()`)
+   *
+   * This is useful for testing.
+   *
+   * @param {string | boolean | Array<string | boolean>} value
+   *
+   * @example
+   * ```js
+   * const promptAgent = PromptAgent.agent();
+   * promptAgent.nextAnswer("toto");
+   *
+   * const input = await question("what is your name?");
+   * assert.equal(input, "toto");
+   * ```
+   */
+  nextAnswer(value) {
+    if (Array.isArray(value)) {
+      this.nextAnswers.push(...value);
+
+      return;
+    }
+
+    this.nextAnswers.push(value);
+  }
+}

package/src/question-prompt.js

@@ -76,6 +76,14 @@ export class QuestionPrompt extends AbstractPrompt {
   }
 
   async question() {
+    if (this.agent.nextAnswers.length > 0) {
+      this.answer = this.agent.nextAnswers.shift();
+      this.#writeAnswer();
+      this.destroy();
+
+      return this.answer;
+    }
+
     this.answer = await this.#question();
 
     if (this.answer === "" && this.defaultValue) {

package/src/select-prompt.js

@@ -114,6 +114,14 @@ export class SelectPrompt extends AbstractPrompt {
   }
 
   async select() {
+    if (this.agent.nextAnswers.length > 0) {
+      const answer = this.agent.nextAnswers.shift();
+      this.#showAnsweredQuestion(answer);
+      this.destroy();
+
+      return answer;
+    }
+
     this.write(SYMBOLS.HideCursor);
     this.#showQuestion();