@optique/clack 1.4.0-dev.2725 → 1.4.0-dev.2728

package/dist/index.cjs

@@ -28,6 +28,7 @@ const __optique_prompt = __toESM(require("@optique/prompt"));
 //#region src/index.ts
 const promptFunctionsOverrideSymbol = Symbol.for("@optique/clack/prompt-functions");
 const defaultPromptFunctions = {
+	spinner: __clack_prompts.spinner,
 	text: __clack_prompts.text,
 	password: __clack_prompts.password,
 	confirm: __clack_prompts.confirm,
@@ -61,18 +62,60 @@ function getPromptFunctions() {
 * @param parser Inner parser that reads CLI values.
 * @param config Type-safe Clack prompt configuration, or a configuration
 *               derived from dependency sources via `derivePromptConfig()`.
-* @param options Shared validation, retry, and cancellation options.
+* @param options Shared validation, retry, cancellation, and optional pending
+*                indicator options.
 * @returns A parser with interactive prompt fallback, always in async mode.
 * @throws {RangeError} If `maxAttempts` is not a positive integer.
+* @throws {DOMException} With name `AbortError` when an OS-delivered SIGINT or
+*                       SIGTERM cancels the pending spinner. Interactive
+*                       Ctrl+C follows Clack's process-exit behavior.
 * @throws {Error} If prompt execution fails with an unexpected error or if the
 *                 inner parser throws while parsing or completing.
 * @since 1.2.0
 * @since 1.3.0 Added shared options and the prompter context.
+* @since 1.4.0 Added the optional pending indicator.
 */
 function prompt(parser, config, options) {
+	const pendingMessage = options?.pendingMessage;
 	const promptWithAdapter = (0, __optique_prompt.createPromptAdapter)({
 		execute: executePromptRaw,
-		getDefaultValue: getConfigDefault
+		getDefaultValue: getConfigDefault,
+		...pendingMessage == null ? {} : { async whilePending(work, { signal }) {
+			if (signal?.aborted) return work();
+			let finished = false;
+			let rejectCancellation;
+			const cancelled = new Promise((_resolve, reject) => {
+				rejectCancellation = reject;
+			});
+			const indicator = getPromptFunctions().spinner({
+				cancelMessage: pendingMessage,
+				onCancel() {
+					if (finished) return;
+					finished = true;
+					signal?.removeEventListener("abort", onAbort);
+					rejectCancellation(new DOMException("Prompt cancelled.", "AbortError"));
+				}
+			});
+			const finish = (outcome) => {
+				if (finished) return;
+				finished = true;
+				signal?.removeEventListener("abort", onAbort);
+				indicator[outcome](pendingMessage);
+			};
+			const onAbort = () => finish("cancel");
+			try {
+				indicator.start(pendingMessage);
+				signal?.addEventListener("abort", onAbort, { once: true });
+				const result = await Promise.race([work(), cancelled]);
+				finish("stop");
+				return result;
+			} catch (error) {
+				finish(signal?.aborted ? "cancel" : "error");
+				throw error;
+			} finally {
+				signal?.removeEventListener("abort", onAbort);
+			}
+		} }
 	});
 	return promptWithAdapter(parser, config, options);
 }

package/dist/index.d.cts

@@ -176,20 +176,41 @@ type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number
  * @since 1.3.0
  */
 type RuntimePromptConfig = ConfirmConfig | NumberPromptConfig | StringPromptConfig | MultiselectConfig;
+/**
+ * Shared prompt options and Clack's derived configuration pending indicator.
+ *
+ * @typeParam TValue Value produced by the wrapped parser.
+ * @since 1.4.0
+ */
+interface ClackPromptOptions<TValue> extends PromptOptions$1<TValue> {
+  /**
+   * Shows a spinner with this message while a derived configuration resolves.
+   * Omit it for silent resolution. An empty string also enables the spinner.
+   * Static configurations ignore this option. Explicit opt-in also shows the
+   * indicator when the resolved configuration has a custom `prompter`.
+   * The final line keeps this message with a success, error, or cancel symbol.
+   */
+  readonly pendingMessage?: string;
+}
 /**
  * Wraps a parser with an interactive Clack prompt fallback.
  *
  * @param parser Inner parser that reads CLI values.
  * @param config Type-safe Clack prompt configuration, or a configuration
  *               derived from dependency sources via `derivePromptConfig()`.
- * @param options Shared validation, retry, and cancellation options.
+ * @param options Shared validation, retry, cancellation, and optional pending
+ *                indicator options.
  * @returns A parser with interactive prompt fallback, always in async mode.
  * @throws {RangeError} If `maxAttempts` is not a positive integer.
+ * @throws {DOMException} With name `AbortError` when an OS-delivered SIGINT or
+ *                       SIGTERM cancels the pending spinner. Interactive
+ *                       Ctrl+C follows Clack's process-exit behavior.
  * @throws {Error} If prompt execution fails with an unexpected error or if the
  *                 inner parser throws while parsing or completing.
  * @since 1.2.0
  * @since 1.3.0 Added shared options and the prompter context.
+ * @since 1.4.0 Added the optional pending indicator.
  */
-declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue> | DerivedPromptConfig$1<RuntimePromptConfig, NoInfer<TValue>>, options?: PromptOptions$1<NoInfer<TValue>>): FluentParser<"async", TValue, TState>;
+declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue> | DerivedPromptConfig$1<RuntimePromptConfig, NoInfer<TValue>>, options?: ClackPromptOptions<NoInfer<TValue>>): FluentParser<"async", TValue, TState>;
 //#endregion
-export { ConfirmConfig, type DerivePromptConfigContext, type DerivePromptConfigNoDepsContext, type DerivePromptConfigNoDepsOptions, type DerivePromptConfigOptions, type DerivePromptConfigsContext, type DerivePromptConfigsOptions, type DerivedPromptConfig, MultiselectConfig, NumberPromptConfig, Option, PasswordConfig, PromptConfig, type PromptExecutionContext, type PromptOptions, type PromptValidator, RuntimePromptConfig, SelectConfig, StringPromptConfig, TextConfig, derivePromptConfig, isDerivedPromptConfig, prompt };
+export { ClackPromptOptions, ConfirmConfig, type DerivePromptConfigContext, type DerivePromptConfigNoDepsContext, type DerivePromptConfigNoDepsOptions, type DerivePromptConfigOptions, type DerivePromptConfigsContext, type DerivePromptConfigsOptions, type DerivedPromptConfig, MultiselectConfig, NumberPromptConfig, Option, PasswordConfig, PromptConfig, type PromptExecutionContext, type PromptOptions, type PromptValidator, RuntimePromptConfig, SelectConfig, StringPromptConfig, TextConfig, derivePromptConfig, isDerivedPromptConfig, prompt };

package/dist/index.d.ts

@@ -176,20 +176,41 @@ type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number
  * @since 1.3.0
  */
 type RuntimePromptConfig = ConfirmConfig | NumberPromptConfig | StringPromptConfig | MultiselectConfig;
+/**
+ * Shared prompt options and Clack's derived configuration pending indicator.
+ *
+ * @typeParam TValue Value produced by the wrapped parser.
+ * @since 1.4.0
+ */
+interface ClackPromptOptions<TValue> extends PromptOptions$1<TValue> {
+  /**
+   * Shows a spinner with this message while a derived configuration resolves.
+   * Omit it for silent resolution. An empty string also enables the spinner.
+   * Static configurations ignore this option. Explicit opt-in also shows the
+   * indicator when the resolved configuration has a custom `prompter`.
+   * The final line keeps this message with a success, error, or cancel symbol.
+   */
+  readonly pendingMessage?: string;
+}
 /**
  * Wraps a parser with an interactive Clack prompt fallback.
  *
  * @param parser Inner parser that reads CLI values.
  * @param config Type-safe Clack prompt configuration, or a configuration
  *               derived from dependency sources via `derivePromptConfig()`.
- * @param options Shared validation, retry, and cancellation options.
+ * @param options Shared validation, retry, cancellation, and optional pending
+ *                indicator options.
  * @returns A parser with interactive prompt fallback, always in async mode.
  * @throws {RangeError} If `maxAttempts` is not a positive integer.
+ * @throws {DOMException} With name `AbortError` when an OS-delivered SIGINT or
+ *                       SIGTERM cancels the pending spinner. Interactive
+ *                       Ctrl+C follows Clack's process-exit behavior.
  * @throws {Error} If prompt execution fails with an unexpected error or if the
  *                 inner parser throws while parsing or completing.
  * @since 1.2.0
  * @since 1.3.0 Added shared options and the prompter context.
+ * @since 1.4.0 Added the optional pending indicator.
  */
-declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue> | DerivedPromptConfig$1<RuntimePromptConfig, NoInfer<TValue>>, options?: PromptOptions$1<NoInfer<TValue>>): FluentParser<"async", TValue, TState>;
+declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue> | DerivedPromptConfig$1<RuntimePromptConfig, NoInfer<TValue>>, options?: ClackPromptOptions<NoInfer<TValue>>): FluentParser<"async", TValue, TState>;
 //#endregion
-export { ConfirmConfig, type DerivePromptConfigContext, type DerivePromptConfigNoDepsContext, type DerivePromptConfigNoDepsOptions, type DerivePromptConfigOptions, type DerivePromptConfigsContext, type DerivePromptConfigsOptions, type DerivedPromptConfig, MultiselectConfig, NumberPromptConfig, Option, PasswordConfig, PromptConfig, type PromptExecutionContext, type PromptOptions, type PromptValidator, RuntimePromptConfig, SelectConfig, StringPromptConfig, TextConfig, derivePromptConfig, isDerivedPromptConfig, prompt };
+export { ClackPromptOptions, ConfirmConfig, type DerivePromptConfigContext, type DerivePromptConfigNoDepsContext, type DerivePromptConfigNoDepsOptions, type DerivePromptConfigOptions, type DerivePromptConfigsContext, type DerivePromptConfigsOptions, type DerivedPromptConfig, MultiselectConfig, NumberPromptConfig, Option, PasswordConfig, PromptConfig, type PromptExecutionContext, type PromptOptions, type PromptValidator, RuntimePromptConfig, SelectConfig, StringPromptConfig, TextConfig, derivePromptConfig, isDerivedPromptConfig, prompt };

package/dist/index.js

@@ -1,10 +1,11 @@
-import { confirm, isCancel, log, multiselect, password, select, text } from "@clack/prompts";
+import { confirm, isCancel, log, multiselect, password, select, spinner, text } from "@clack/prompts";
 import { formatMessage, message } from "@optique/core/message";
 import { createPromptAdapter, derivePromptConfig, isDerivedPromptConfig } from "@optique/prompt";
 
 //#region src/index.ts
 const promptFunctionsOverrideSymbol = Symbol.for("@optique/clack/prompt-functions");
 const defaultPromptFunctions = {
+	spinner,
 	text,
 	password,
 	confirm,
@@ -38,18 +39,60 @@ function getPromptFunctions() {
 * @param parser Inner parser that reads CLI values.
 * @param config Type-safe Clack prompt configuration, or a configuration
 *               derived from dependency sources via `derivePromptConfig()`.
-* @param options Shared validation, retry, and cancellation options.
+* @param options Shared validation, retry, cancellation, and optional pending
+*                indicator options.
 * @returns A parser with interactive prompt fallback, always in async mode.
 * @throws {RangeError} If `maxAttempts` is not a positive integer.
+* @throws {DOMException} With name `AbortError` when an OS-delivered SIGINT or
+*                       SIGTERM cancels the pending spinner. Interactive
+*                       Ctrl+C follows Clack's process-exit behavior.
 * @throws {Error} If prompt execution fails with an unexpected error or if the
 *                 inner parser throws while parsing or completing.
 * @since 1.2.0
 * @since 1.3.0 Added shared options and the prompter context.
+* @since 1.4.0 Added the optional pending indicator.
 */
 function prompt(parser, config, options) {
+	const pendingMessage = options?.pendingMessage;
 	const promptWithAdapter = createPromptAdapter({
 		execute: executePromptRaw,
-		getDefaultValue: getConfigDefault
+		getDefaultValue: getConfigDefault,
+		...pendingMessage == null ? {} : { async whilePending(work, { signal }) {
+			if (signal?.aborted) return work();
+			let finished = false;
+			let rejectCancellation;
+			const cancelled = new Promise((_resolve, reject) => {
+				rejectCancellation = reject;
+			});
+			const indicator = getPromptFunctions().spinner({
+				cancelMessage: pendingMessage,
+				onCancel() {
+					if (finished) return;
+					finished = true;
+					signal?.removeEventListener("abort", onAbort);
+					rejectCancellation(new DOMException("Prompt cancelled.", "AbortError"));
+				}
+			});
+			const finish = (outcome) => {
+				if (finished) return;
+				finished = true;
+				signal?.removeEventListener("abort", onAbort);
+				indicator[outcome](pendingMessage);
+			};
+			const onAbort = () => finish("cancel");
+			try {
+				indicator.start(pendingMessage);
+				signal?.addEventListener("abort", onAbort, { once: true });
+				const result = await Promise.race([work(), cancelled]);
+				finish("stop");
+				return result;
+			} catch (error) {
+				finish(signal?.aborted ? "cancel" : "error");
+				throw error;
+			} finally {
+				signal?.removeEventListener("abort", onAbort);
+			}
+		} }
 	});
 	return promptWithAdapter(parser, config, options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/clack",
-  "version": "1.4.0-dev.2725",
+  "version": "1.4.0-dev.2728",
   "description": "Interactive prompt support for Optique via Clack",
   "keywords": [
     "CLI",
@@ -62,12 +62,12 @@
   "sideEffects": false,
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@optique/core": "1.4.0-dev.2725+a2d21dc2",
-    "@optique/prompt": "1.4.0-dev.2725+a2d21dc2"
+    "@optique/core": "1.4.0-dev.2728+5829a43f",
+    "@optique/prompt": "1.4.0-dev.2728+5829a43f"
   },
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2725+a2d21dc2",
-    "@optique/run": "1.4.0-dev.2725+a2d21dc2",
+    "@optique/env": "1.4.0-dev.2728+5829a43f",
+    "@optique/run": "1.4.0-dev.2728+5829a43f",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
@@ -78,7 +78,7 @@
     "prepublish": "tsdown",
     "test": "node --test",
     "test:bun": "bun test",
-    "test:deno": "deno test --allow-env",
-    "test-all": "tsdown && node --test && bun test && deno test --allow-env"
+    "test:deno": "deno test --allow-env --allow-run",
+    "test-all": "tsdown && node --test && bun test && deno test --allow-env --allow-run"
   }
 }