@topcli/prompts 3.1.0 → 4.0.0

package/README.md

@@ -55,6 +55,8 @@ Simple prompt, similar to `rl.question()` with an improved UI.
 
 Use `options.defaultValue` to set a default value.
 
+Use `options.hint` to display a hint alongside the question.
+
 Use `options.secure` if you need to hide both input and answer. You can provide either a **boolean** or an **object** which allows to configure a `placeholder` such as `*`.
 
 Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
@@ -245,14 +247,30 @@ Use `options.skip` to skip prompt. It will return `options.initial` (`false` by
 
 The `PromptAgent` class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
 
+#### Shared instance
+
+`PromptAgent.shared()` returns a singleton shared across all prompt calls that do not receive an explicit `agent` option. Suitable for simple test setups, but beware of state leaking between tests.
+
 ```ts
-const agent = PromptAgent.agent();
+const agent = PromptAgent.shared();
 agent.nextAnswer("John");
 
 const input = await question("What's your name?");
 assert.equal(input, "John");
 ```
 
+#### Individual instance
+
+For better isolation (e.g. in unit tests), create a dedicated `PromptAgent` and pass it via the `agent` option. This avoids any state leaking from the shared instance.
+
+```ts
+const agent = new PromptAgent();
+agent.nextAnswer("John");
+
+const input = await question("What's your name?", { agent });
+assert.equal(input, "John");
+```
+
 > [!WARNING]
 > Answers set with `PromptAgent` will **bypass** any logical & validation rules.
 > Examples:
@@ -311,6 +329,7 @@ export type TransformationResponse<T> = InvalidResponse | ValidTransformationRes
 
 export interface QuestionOptions<T = string> extends AbstractPromptOptions {
   defaultValue?: string;
+  hint?: string;
   validators?: PromptValidator<string>[];
   transformer?: PromptTransformer<T>;
   secure?: boolean | { placeholder: string };

package/dist/index.d.mts

@@ -34,8 +34,7 @@ declare class PromptAgent<T = string> {
    * When not empty, any prompt will be answered by the first answer in this list.
    */
   nextAnswers: T[];
-  static agent<T>(): PromptAgent<T>;
-  constructor(instancier: symbol);
+  static shared<T>(): PromptAgent<any>;
   /**
    * Programmatically set the next answer for any prompt (`question()`, `confirm()`, `select()`)
    *
@@ -43,14 +42,15 @@ declare class PromptAgent<T = string> {
    *
    * @example
    * ```js
-   * const promptAgent = PromptAgent.agent();
+   * const promptAgent = PromptAgent.shared();
    * promptAgent.nextAnswer("toto");
    *
    * const input = await question("what is your name?");
    * assert.equal(input, "toto");
    * ```
    */
-  nextAnswer(value: T): void;
+  nextAnswer(value: T | T[]): void;
+  clear(): void;
 }
 //#endregion
 //#region src/transformers.d.ts
@@ -83,11 +83,13 @@ interface AbstractPromptOptions {
   message: string;
   skip?: boolean;
   signal?: AbortSignal;
+  agent?: PromptAgent<string | boolean>;
 }
 //#endregion
 //#region src/prompts/question.d.ts
 interface QuestionOptions<T = string> extends AbstractPromptOptions {
   defaultValue?: string;
+  hint?: string;
   validators?: PromptValidator<string>[];
   transformer?: PromptTransformer<T>;
   secure?: boolean | {
@@ -135,5 +137,4 @@ declare const transformers: {
   url: typeof url;
 };
 //#endregion
-export { type AbstractPromptOptions, type Choice, type ConfirmOptions, type InvalidResponse, type InvalidResponseObject, type MultiselectOptions, PromptAgent, type PromptTransformer, type PromptValidator, type QuestionOptions, type SelectOptions, type Separator, type TransformationResponse, type ValidResponse, type ValidResponseObject, type ValidTransformationResponse, type ValidationResponse, type ValidationResponseObject, confirm, multiselect, question, select, transformers, validators };
-//# sourceMappingURL=index.d.mts.map
+export { type AbstractPromptOptions, type Choice, type ConfirmOptions, type InvalidResponse, type InvalidResponseObject, type MultiselectOptions, PromptAgent, type PromptTransformer, type PromptValidator, type QuestionOptions, type SelectOptions, type Separator, type TransformationResponse, type ValidResponse, type ValidResponseObject, type ValidTransformationResponse, type ValidationResponse, type ValidationResponseObject, confirm, multiselect, question, select, transformers, validators };

package/dist/index.mjs

@@ -28,22 +28,16 @@ function resultError(result) {
 }
 //#endregion
 //#region src/prompt-agent.ts
-const kPrivateInstancier = Symbol("instancier");
 var PromptAgent = class PromptAgent {
 	/**
 	* The prompts answers queue.
 	* When not empty, any prompt will be answered by the first answer in this list.
 	*/
 	nextAnswers = [];
-	/**
-	* The shared PromptAgent.
-	*/
-	static #this;
-	static agent() {
-		return this.#this ??= new PromptAgent(kPrivateInstancier);
-	}
-	constructor(instancier) {
-		if (instancier !== kPrivateInstancier) throw new Error("Cannot instanciate PromptAgent, use PromptAgent.agent() instead");
+	static #sharedInstance;
+	static shared() {
+		this.#sharedInstance ??= new PromptAgent();
+		return this.#sharedInstance;
 	}
 	/**
 	* Programmatically set the next answer for any prompt (`question()`, `confirm()`, `select()`)
@@ -52,7 +46,7 @@ var PromptAgent = class PromptAgent {
 	*
 	* @example
 	* ```js
-	* const promptAgent = PromptAgent.agent();
+	* const promptAgent = PromptAgent.shared();
 	* promptAgent.nextAnswer("toto");
 	*
 	* const input = await question("what is your name?");
@@ -60,11 +54,11 @@ var PromptAgent = class PromptAgent {
 	* ```
 	*/
 	nextAnswer(value) {
-		if (Array.isArray(value)) {
-			this.nextAnswers.push(...value);
-			return;
-		}
-		this.nextAnswers.push(value);
+		if (Array.isArray(value)) this.nextAnswers.push(...value);
+		else this.nextAnswers.push(value);
+	}
+	clear() {
+		this.nextAnswers = [];
 	}
 };
 //#endregion
@@ -105,28 +99,25 @@ function integer() {
 }
 function url() {
 	return { transform(input) {
+		if (URL.canParse(input)) return {
+			isValid: true,
+			transformed: new URL(input)
+		};
 		try {
+			const parsed = new URL(`https://${input}`);
+			if (!parsed.hostname.includes(".") && parsed.hostname !== "localhost") return {
+				isValid: false,
+				error: "invalid URL"
+			};
 			return {
 				isValid: true,
-				transformed: new URL(input)
+				transformed: parsed
 			};
 		} catch {
-			try {
-				const parsed = new URL(`https://${input}`);
-				if (!parsed.hostname.includes(".") && parsed.hostname !== "localhost") return {
-					isValid: false,
-					error: "invalid URL"
-				};
-				return {
-					isValid: true,
-					transformed: parsed
-				};
-			} catch {
-				return {
-					isValid: false,
-					error: "invalid URL"
-				};
-			}
+			return {
+				isValid: false,
+				error: "invalid URL"
+			};
 		}
 	} };
 }
@@ -157,7 +148,7 @@ var AbstractPrompt = class AbstractPrompt extends EventEmitter {
 	constructor(options) {
 		super();
 		if (this.constructor === AbstractPrompt) throw new Error("AbstractPrompt can't be instantiated.");
-		const { stdin: input = process.stdin, stdout: output = process.stdout, message, signal, skip = false } = options;
+		const { stdin: input = process.stdin, stdout: output = process.stdout, message, signal, skip = false, agent = PromptAgent.shared() } = options;
 		if (typeof message !== "string") throw new TypeError(`message must be string, ${typeof message} given.`);
 		if (!output.isTTY) Object.assign(output, {
 			moveCursor: () => void 0,
@@ -169,7 +160,7 @@ var AbstractPrompt = class AbstractPrompt extends EventEmitter {
 		this.signal = signal;
 		this.skip = skip;
 		this.history = [];
-		this.agent = PromptAgent.agent();
+		this.agent = agent;
 		if (this.stdout.isTTY) this.stdin.setRawMode(true);
 		this.rl = readline.createInterface({
 			input,
@@ -270,6 +261,7 @@ const SYMBOLS = {
 //#region src/prompts/question.ts
 var QuestionPrompt = class extends AbstractPrompt {
 	defaultValue;
+	hint;
 	tip;
 	questionSuffixError;
 	answer;
@@ -280,11 +272,12 @@ var QuestionPrompt = class extends AbstractPrompt {
 	#secure;
 	#securePlaceholder = null;
 	constructor(options) {
-		const { defaultValue, validators = [], transformer, secure = false, ...baseOptions } = options;
+		const { defaultValue, hint, validators = [], transformer, secure = false, ...baseOptions } = options;
 		super({ ...baseOptions });
 		if (validators.length > 0 && transformer !== void 0) throw new Error("validators and transformer are mutually exclusive");
 		if (defaultValue && typeof defaultValue !== "string") throw new TypeError("defaultValue must be a string");
 		this.defaultValue = defaultValue;
+		this.hint = hint;
 		this.tip = this.defaultValue ? ` (${this.defaultValue})` : "";
 		this.#validators = validators;
 		this.#transformer = transformer;
@@ -294,6 +287,9 @@ var QuestionPrompt = class extends AbstractPrompt {
 		} else this.#secure = Boolean(secure);
 		this.questionSuffixError = "";
 	}
+	get formattedHint() {
+		return this.hint ? styleText("gray", this.hint) : "";
+	}
 	#question() {
 		const { resolve, promise } = Promise.withResolvers();
 		const questionQuery = this.#getQuestionQuery();
@@ -307,10 +303,12 @@ var QuestionPrompt = class extends AbstractPrompt {
 		return promise;
 	}
 	#getQuestionQuery() {
-		return `${styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`)} ${this.questionSuffixError}`;
+		const hintPart = this.formattedHint ? ` ${this.formattedHint}` : "";
+		return `${styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`)}${hintPart} ${this.questionSuffixError}`;
 	}
 	#setQuestionSuffixError(error) {
-		this.questionSuffixError = styleText("red", `[${error}] `);
+		const suffix = styleText("red", `[${error}] `);
+		this.questionSuffixError = suffix;
 	}
 	#writeAnswer() {
 		const prefix = this.answer ? SYMBOLS.Tick : SYMBOLS.Cross;
@@ -320,7 +318,7 @@ var QuestionPrompt = class extends AbstractPrompt {
 		this.write(`${prefix} ${styleText("bold", this.message)} ${SYMBOLS.Pointer} ${stylizedAnswer}${EOL}`);
 	}
 	#getValidatingQuery(dotCount) {
-		return `${styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`)} ${styleText("yellow", `[validating${".".repeat(dotCount)}]`)}${EOL}`;
+		return `${styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`)}${this.formattedHint ? ` ${this.formattedHint}` : ""} ${styleText("yellow", `[validating${".".repeat(dotCount)}]`)}${EOL}`;
 	}
 	async #runTransformer() {
 		const result = this.#transformer.transform(this.answer);
@@ -420,7 +418,7 @@ var QuestionPrompt = class extends AbstractPrompt {
 };
 //#endregion
 //#region src/prompts/confirm.ts
-const kToggleKeys = new Set([
+const kToggleKeys = /* @__PURE__ */ new Set([
 	"left",
 	"right",
 	"tab",
@@ -1171,5 +1169,3 @@ const transformers = {
 };
 //#endregion
 export { PromptAgent, confirm, multiselect, question, select, transformers, validators };
-
-//# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@topcli/prompts",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "Node.js user input library for command-line interfaces.",
   "type": "module",
   "scripts": {
-    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "build": "tsdown src/index.ts --dts --clean",
     "prepublishOnly": "npm run build",
     "test-only": "node --test ./test/**/*.test.ts",
-    "test-types": "npm run build && tsd && attw --pack .",
+    "test-types": "npm run build && tsd && attw --pack . --profile esm-only",
     "test": "c8 -r html npm run test-only && npm run test-types",
     "lint": "eslint src test",
     "lint:fix": "eslint . --fix"
@@ -21,14 +21,8 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
     }
   },
   "keywords": [
@@ -45,10 +39,10 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@openally/config.eslint": "^2.2.0",
     "@openally/config.typescript": "^1.2.1",
-    "@types/node": "^25.0.3",
+    "@types/node": "^26.0.1",
     "c8": "^11.0.0",
     "tsd": "^0.33.0",
-    "tsdown": "0.21.7",
+    "tsdown": "0.22.3",
     "typescript": "^6.0.2"
   },
   "engines": {