@topcli/prompts 1.1.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
 
@@ -27,20 +27,15 @@ $ yarn add @topcli/prompts
 You can locally run `node ./demo.js`
 
 ```js
-import { prompt, confirm, select } from '@topcli/prompts';
+import { question, confirm, select } from "@topcli/prompts";
 
-const kTestRunner = ['node', 'tap', 'tape', 'vitest', 'mocha', 'ava'];
+const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];
 
-const name = await prompt('Project name ?');
-const runner = await select('Choose a test runner', {
-  choices: kTestRunner,
-  maxVisible: 5
-});
-const isCLI = await confirm('Your project is a CLI ?', {
-  initial: true
-});
+const name = await question("Project name ?", { defaultValue: "foo" });
+const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
+const isCLI = await confirm("Your project is a CLI ?", { initial: true });
 
-console.log(name, runner, isCLI);^
+console.log(name, runner, isCLI);
 ```
 
 ## API
@@ -94,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;
 }
 ```
 
@@ -141,6 +162,7 @@ export interface ConfirmOptions {
       <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/thomas-gentilhomme/"><img src="https://avatars.githubusercontent.com/u/4438263?v=4?s=100" width="100px;" alt="Gentilhomme"/><br /><sub><b>Gentilhomme</b></sub></a><br /><a href="https://github.com/TopCli/prompts/pulls?q=is%3Apr+reviewed-by%3Afraxken" title="Reviewed Pull Requests">👀</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://tonygo.dev"><img src="https://avatars0.githubusercontent.com/u/22824417?v=4?s=100" width="100px;" alt="Tony Gorez"/><br /><sub><b>Tony Gorez</b></sub></a><br /><a href="https://github.com/TopCli/prompts/pulls?q=is%3Apr+reviewed-by%3Atony-go" title="Reviewed Pull Requests">👀</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://sofiand.github.io/portfolio-client/"><img src="https://avatars.githubusercontent.com/u/39944043?v=4?s=100" width="100px;" alt="Yefis"/><br /><sub><b>Yefis</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=SofianD" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=SofianD" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://justie.dev"><img src="https://avatars.githubusercontent.com/u/7118300?v=4?s=100" width="100px;" alt="Ben"/><br /><sub><b>Ben</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=JUSTIVE" title="Documentation">📖</a> <a href="#maintenance-JUSTIVE" title="Maintenance">🚧</a></td>
     </tr>
   </tbody>
 </table>

package/index.d.ts

@@ -1,6 +1,10 @@
-export interface PromptOptions {
-  defaultValue?: string;
-  validators?: Validator[];
+export interface SharedOptions {
+  stdin?: NodeJS.ReadStream & {
+    fd: 0;
+  };
+  stdout?: NodeJS.WriteStream & {
+    fd: 1;
+  };
 }
 
 export interface Validator {
@@ -8,24 +12,56 @@ 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;
 }
 
-export function question(message: string, options?: PromptOptions): Promise<string>;
+export function question(message: string, options?: QuestionOptions): Promise<string>;
 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,9 +1,9 @@
 {
   "name": "@topcli/prompts",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Node.js user input library for command-line interfaces.",
   "scripts": {
-    "test": "node --loader=esmock --test test/",
+    "test": "node --no-warnings=ExperimentalWarning --loader=esmock --test test/",
     "coverage": "c8 -r html npm run test",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
@@ -24,14 +24,15 @@
   "type": "module",
   "devDependencies": {
     "@nodesecure/eslint-config": "^1.7.0",
-    "c8": "^7.13.0",
-    "eslint": "^8.38.0",
-    "esmock": "^2.1.0"
+    "@types/node": "^20.4.5",
+    "c8": "^8.0.0",
+    "eslint": "^8.44.0",
+    "esmock": "^2.3.1"
   },
   "dependencies": {
     "is-unicode-supported": "^1.3.0",
     "kleur": "^4.1.5",
-    "strip-ansi": "^7.0.1"
+    "strip-ansi": "^7.1.0"
   },
   "engines": {
     "node": ">=14"

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

@@ -8,7 +8,25 @@ import kleur from "kleur";
 import { AbstractPrompt } from "./abstract-prompt.js";
 import { SYMBOLS } from "./constants.js";
 
+// CONSTANTS
+const kToggleKeys = new Set([
+  "left",
+  "right",
+  "tab",
+  "q",
+  "a",
+  "d",
+  "h",
+  "j",
+  "k",
+  "l",
+  "space"
+]);
+
 export class ConfirmPrompt extends AbstractPrompt {
+  #boundKeyPressEvent;
+  #boundExitEvent;
+
   constructor(message, options = {}) {
     const {
       stdin = process.stdin,
@@ -17,55 +35,92 @@ export class ConfirmPrompt extends AbstractPrompt {
     } = options;
     super(message, stdin, stdout);
 
-    const Yes = kleur.bold("Yes");
-    const No = kleur.bold("No");
-    this.tip = kleur.gray(initial ? `(${Yes}/no)` : `(yes/${No})`);
-
     this.initial = initial;
+    this.selectedValue = initial;
+  }
+
+  #getHint() {
+    const Yes = kleur.bold().underline().cyan("Yes");
+    const No = kleur.bold().underline().cyan("No");
+
+    return this.selectedValue ? `${Yes}/No` : `Yes/${No}`;
+  }
+
+  #render() {
+    this.write(this.#getQuestionQuery());
   }
 
   #question() {
     return new Promise((resolve) => {
       const questionQuery = this.#getQuestionQuery();
 
-      this.rl.question(questionQuery,
-        (answer) => {
-          this.history.push(questionQuery + answer);
+      this.write(questionQuery);
+
+      this.#boundKeyPressEvent = this.#onKeypress.bind(this, resolve);
+      this.stdin.on("keypress", this.#boundKeyPressEvent);
 
-          resolve(answer);
-        }
-      );
+      this.#boundExitEvent = this.#onProcessExit.bind(this);
+      process.once("exit", this.#boundExitEvent);
     });
   }
 
+  #onKeypress(resolve, value, key) {
+    this.stdin.pause();
+    this.stdout.moveCursor(-this.#getQuestionQuery().length, 0);
+    this.stdout.clearScreenDown(() => this.stdin.resume());
+
+    if (key.name === "return") {
+      resolve(this.selectedValue);
+
+      return;
+    }
+
+    if (kToggleKeys.has(key.name)) {
+      this.selectedValue = !this.selectedValue;
+    }
+
+    this.#render();
+  }
+
+  #onProcessExit() {
+    this.stdin.off("keypress", this.#boundKeyPressEvent);
+  }
+
   #getQuestionQuery() {
     const query = kleur.bold(`${SYMBOLS.QuestionMark} ${this.message}`);
 
-    return `${query} ${this.tip} `;
+    return `${query} ${this.#getHint()}`;
   }
 
   #onQuestionAnswer() {
     this.clearLastLine();
-    this.write(`${this.answer ? SYMBOLS.Tick : SYMBOLS.Cross} ${kleur.bold(this.message)}${EOL}`);
+    this.write(`${this.selectedValue ? SYMBOLS.Tick : SYMBOLS.Cross} ${kleur.bold(this.message)}${EOL}`);
   }
 
-  #validateResult(result) {
-    if (typeof result !== "string") {
-      return false;
+  async confirm() {
+    if (this.agent.nextAnswers.length > 0) {
+      const answer = this.agent.nextAnswers.shift();
+      this.selectedValue = answer;
+      this.#onQuestionAnswer();
+      this.destroy();
+
+      return answer;
     }
 
-    return ["y", "yes", "no", "n"].includes(result.toLowerCase());
-  }
+    this.write(SYMBOLS.HideCursor);
 
-  async confirm() {
     try {
-      const result = await this.#question();
-      this.answer = this.#validateResult(result) ? ["y", "yes"].includes(result.toLocaleLowerCase()) : this.initial;
+      await this.#question();
       this.#onQuestionAnswer();
 
-      return this.answer;
+      return this.selectedValue;
     }
     finally {
+      this.write(SYMBOLS.ShowCursor);
+
+      this.#onProcessExit();
+      process.off("exit", this.#boundExitEvent);
+
       this.destroy();
     }
   }

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