@optique/prompt 1.4.0-dev.2603 → 1.4.0-dev.2604

package/dist/index.cjs

@@ -40,14 +40,22 @@ const derivedPromptConfigMarker = Symbol.for("@optique/prompt/derivedPromptConfi
 function isDerivedPromptConfig(config) {
 	return config != null && typeof config === "object" && derivedPromptConfigMarker in config && config[derivedPromptConfigMarker] === true;
 }
-function derivePromptConfig(source, resolver, options) {
+function derivePromptConfig(source, resolverOrOptions, options) {
+	if (typeof source === "function") return deriveNoDepsPromptConfig(source, resolverOrOptions);
+	const resolver = resolverOrOptions;
 	const isTuple = Array.isArray(source);
 	const dependencies = isTuple ? source : [source];
 	if (dependencies.length === 0) throw new TypeError("derivePromptConfig() requires at least one dependency source.");
 	const infos = dependencies.map(__optique_core_dependency.getDependencySourceInfo);
 	const singleDefault = options?.defaultValue;
 	const defaultValues = isTuple ? options?.defaultValues : singleDefault == null ? void 0 : () => [singleDefault()];
-	const resolve = isTuple ? (values, usedDefaults) => resolver(values, { usedDefaults }) : (values, usedDefaults) => resolver(values[0], { usedDefault: usedDefaults[0] });
+	const resolve = isTuple ? (values, usedDefaults, context) => resolver(values, {
+		usedDefaults,
+		...context
+	}) : (values, usedDefaults, context) => resolver(values[0], {
+		usedDefault: usedDefaults[0],
+		...context
+	});
 	return {
 		[derivedPromptConfigMarker]: true,
 		dependencies,
@@ -61,6 +69,19 @@ function derivePromptConfig(source, resolver, options) {
 		}
 	};
 }
+function deriveNoDepsPromptConfig(resolver, options) {
+	return {
+		[derivedPromptConfigMarker]: true,
+		dependencies: [],
+		dependencyIds: [],
+		dependencyLabels: [],
+		resolve: (_values, _usedDefaults, context) => resolver({ ...context }),
+		...options?.when == null ? {} : {
+			when: options.when,
+			otherwise: options.otherwise
+		}
+	};
+}
 function describeThrown(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -73,7 +94,7 @@ function describeThrown(error) {
 * (synchronous throws and rejections alike) become prompt failures so
 * the scheduler treats them like a cancelled prompt.
 */
-async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel) {
+async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel, signal) {
 	const runtime = exec?.dependencyRuntime;
 	const ids = config.dependencyIds;
 	if (runtime != null) {
@@ -124,7 +145,7 @@ async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel) {
 	try {
 		return {
 			ok: true,
-			config: await config.resolve(values, usedDefaults)
+			config: await config.resolve(values, usedDefaults, signal === void 0 ? {} : { signal })
 		};
 	} catch (error) {
 		return {
@@ -288,8 +309,7 @@ function createPromptAdapter(adapter) {
 			if (!isDerivedPromptConfig(config)) resolvedConfig = config;
 			else {
 				const source = promptedParser.dependencyMetadata?.source;
-				const resolved = await resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar);
-				throwIfPromptAborted(signal);
+				const resolved = await racePromptWorkWithAbort(signal, () => resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar, signal));
 				if (!resolved.ok) return {
 					success: false,
 					error: resolved.error

package/dist/index.d.cts

@@ -55,8 +55,11 @@ interface PromptOptions<TValue> {
    */
   readonly maxAttempts?: number;
   /**
-   * Signal that stops the active adapter execution or validator.  Its reason
-   * is propagated to the caller without becoming a parse failure.
+   * Signal that stops the active adapter execution, validator, or derived
+   * configuration resolver.  Its reason is propagated to the caller without
+   * becoming a parse failure.  Derived configuration resolvers also receive
+   * it so that they can cancel their own work.
+   * @since 1.4.0 Also stops a pending derived configuration resolver.
    */
   readonly signal?: AbortSignal;
 }
@@ -125,6 +128,25 @@ interface DerivePromptConfigContext {
    * values and are not reported here.
    */
   readonly usedDefault: boolean;
+  /**
+   * Signal supplied through the prompt's shared options, when present.
+   * Pass it to cancellable work such as network requests.
+   * @since 1.4.0
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Context passed to a prompt configuration resolver that has no
+ * dependencies.
+ *
+ * @since 1.4.0
+ */
+interface DerivePromptConfigNoDepsContext {
+  /**
+   * Signal supplied through the prompt's shared options, when present.
+   * Pass it to cancellable work such as network requests.
+   */
+  readonly signal?: AbortSignal;
 }
 /**
  * Context passed to a multi-dependency prompt configuration resolver.
@@ -139,6 +161,12 @@ interface DerivePromptConfigsContext<Deps extends readonly AnyDependencySource[]
    * than a published source value.
    */
   readonly usedDefaults: { readonly [K in keyof Deps]: boolean };
+  /**
+   * Signal supplied through the prompt's shared options, when present.
+   * Pass it to cancellable work such as network requests.
+   * @since 1.4.0
+   */
+  readonly signal?: AbortSignal;
 }
 /**
  * Options for a single-dependency {@link derivePromptConfig} call.
@@ -161,6 +189,19 @@ type DerivePromptConfigOptions<TDefault, TOtherwise> = {
   readonly when: () => boolean | Promise<boolean>;
   readonly otherwise: TOtherwise;
 });
+/**
+ * Options for a zero-dependency {@link derivePromptConfig} call.
+ *
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.4.0
+ */
+type DerivePromptConfigNoDepsOptions<TOtherwise> = {
+  readonly when?: never;
+  readonly otherwise?: never;
+} | {
+  readonly when: () => boolean | Promise<boolean>;
+  readonly otherwise: TOtherwise;
+};
 /**
  * Options for a multi-dependency {@link derivePromptConfig} call.
  *
@@ -206,10 +247,11 @@ interface DerivedPromptConfig<TConfig, TOtherwise = never> {
   readonly dependencyLabels: readonly string[];
   /**
    * Resolves the adapter configuration from dependency values.  Receives
-   * one value and one used-default flag per dependency position.
+   * one value and one used-default flag per dependency position, and
+   * optionally the abort signal to forward to the resolver.
    * @internal
    */
-  readonly resolve: (values: readonly unknown[], usedDefaults: readonly boolean[]) => TConfig | Promise<TConfig>;
+  readonly resolve: (values: readonly unknown[], usedDefaults: readonly boolean[], context?: DerivePromptConfigNoDepsContext) => TConfig | Promise<TConfig>;
   /**
    * Lazily evaluated fallbacks, one per dependency position.
    * @internal
@@ -229,6 +271,24 @@ interface DerivedPromptConfig<TConfig, TOtherwise = never> {
  * @since 1.3.0
  */
 declare function isDerivedPromptConfig(config: unknown): config is DerivedPromptConfig<unknown, unknown>;
+/**
+ * Derives a prompt configuration without any dependency source.
+ *
+ * The resolver may return the configuration synchronously or
+ * asynchronously.  It runs only during the real completion phase,
+ * immediately before the adapter executes, so it can load data such as
+ * the choices of a selection prompt without running for command-line
+ * values, help, or suggestions.
+ *
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @param resolver Produces the adapter configuration.  It receives the
+ *                 prompt's abort signal, when one is supplied.
+ * @param options Optional runtime condition.
+ * @returns A derived configuration accepted by `prompt()` wrappers.
+ * @since 1.4.0
+ */
+declare function derivePromptConfig<TConfig, const TOtherwise = never>(resolver: (context: DerivePromptConfigNoDepsContext) => TConfig | Promise<TConfig>, options?: DerivePromptConfigNoDepsOptions<TOtherwise>): DerivedPromptConfig<TConfig, TOtherwise>;
 /**
  * Derives a prompt configuration from one dependency source value.
  *
@@ -299,4 +359,4 @@ type PromptConfigInput<TConfig, TValue> = (TConfig & PromptCondition<TValue>) |
  */
 declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfigInput<TConfig, TValue>, options?: PromptOptions<NoInfer<TValue>>) => FluentParser<"async", TValue, TState>;
 //#endregion
-export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, PromptExecutionContext, PromptOptions, PromptValidator, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };
+export { DerivePromptConfigContext, DerivePromptConfigNoDepsContext, DerivePromptConfigNoDepsOptions, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, PromptExecutionContext, PromptOptions, PromptValidator, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/dist/index.d.ts

@@ -55,8 +55,11 @@ interface PromptOptions<TValue> {
    */
   readonly maxAttempts?: number;
   /**
-   * Signal that stops the active adapter execution or validator.  Its reason
-   * is propagated to the caller without becoming a parse failure.
+   * Signal that stops the active adapter execution, validator, or derived
+   * configuration resolver.  Its reason is propagated to the caller without
+   * becoming a parse failure.  Derived configuration resolvers also receive
+   * it so that they can cancel their own work.
+   * @since 1.4.0 Also stops a pending derived configuration resolver.
    */
   readonly signal?: AbortSignal;
 }
@@ -125,6 +128,25 @@ interface DerivePromptConfigContext {
    * values and are not reported here.
    */
   readonly usedDefault: boolean;
+  /**
+   * Signal supplied through the prompt's shared options, when present.
+   * Pass it to cancellable work such as network requests.
+   * @since 1.4.0
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Context passed to a prompt configuration resolver that has no
+ * dependencies.
+ *
+ * @since 1.4.0
+ */
+interface DerivePromptConfigNoDepsContext {
+  /**
+   * Signal supplied through the prompt's shared options, when present.
+   * Pass it to cancellable work such as network requests.
+   */
+  readonly signal?: AbortSignal;
 }
 /**
  * Context passed to a multi-dependency prompt configuration resolver.
@@ -139,6 +161,12 @@ interface DerivePromptConfigsContext<Deps extends readonly AnyDependencySource[]
    * than a published source value.
    */
   readonly usedDefaults: { readonly [K in keyof Deps]: boolean };
+  /**
+   * Signal supplied through the prompt's shared options, when present.
+   * Pass it to cancellable work such as network requests.
+   * @since 1.4.0
+   */
+  readonly signal?: AbortSignal;
 }
 /**
  * Options for a single-dependency {@link derivePromptConfig} call.
@@ -161,6 +189,19 @@ type DerivePromptConfigOptions<TDefault, TOtherwise> = {
   readonly when: () => boolean | Promise<boolean>;
   readonly otherwise: TOtherwise;
 });
+/**
+ * Options for a zero-dependency {@link derivePromptConfig} call.
+ *
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.4.0
+ */
+type DerivePromptConfigNoDepsOptions<TOtherwise> = {
+  readonly when?: never;
+  readonly otherwise?: never;
+} | {
+  readonly when: () => boolean | Promise<boolean>;
+  readonly otherwise: TOtherwise;
+};
 /**
  * Options for a multi-dependency {@link derivePromptConfig} call.
  *
@@ -206,10 +247,11 @@ interface DerivedPromptConfig<TConfig, TOtherwise = never> {
   readonly dependencyLabels: readonly string[];
   /**
    * Resolves the adapter configuration from dependency values.  Receives
-   * one value and one used-default flag per dependency position.
+   * one value and one used-default flag per dependency position, and
+   * optionally the abort signal to forward to the resolver.
    * @internal
    */
-  readonly resolve: (values: readonly unknown[], usedDefaults: readonly boolean[]) => TConfig | Promise<TConfig>;
+  readonly resolve: (values: readonly unknown[], usedDefaults: readonly boolean[], context?: DerivePromptConfigNoDepsContext) => TConfig | Promise<TConfig>;
   /**
    * Lazily evaluated fallbacks, one per dependency position.
    * @internal
@@ -229,6 +271,24 @@ interface DerivedPromptConfig<TConfig, TOtherwise = never> {
  * @since 1.3.0
  */
 declare function isDerivedPromptConfig(config: unknown): config is DerivedPromptConfig<unknown, unknown>;
+/**
+ * Derives a prompt configuration without any dependency source.
+ *
+ * The resolver may return the configuration synchronously or
+ * asynchronously.  It runs only during the real completion phase,
+ * immediately before the adapter executes, so it can load data such as
+ * the choices of a selection prompt without running for command-line
+ * values, help, or suggestions.
+ *
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @param resolver Produces the adapter configuration.  It receives the
+ *                 prompt's abort signal, when one is supplied.
+ * @param options Optional runtime condition.
+ * @returns A derived configuration accepted by `prompt()` wrappers.
+ * @since 1.4.0
+ */
+declare function derivePromptConfig<TConfig, const TOtherwise = never>(resolver: (context: DerivePromptConfigNoDepsContext) => TConfig | Promise<TConfig>, options?: DerivePromptConfigNoDepsOptions<TOtherwise>): DerivedPromptConfig<TConfig, TOtherwise>;
 /**
  * Derives a prompt configuration from one dependency source value.
  *
@@ -299,4 +359,4 @@ type PromptConfigInput<TConfig, TValue> = (TConfig & PromptCondition<TValue>) |
  */
 declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfigInput<TConfig, TValue>, options?: PromptOptions<NoInfer<TValue>>) => FluentParser<"async", TValue, TState>;
 //#endregion
-export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, PromptExecutionContext, PromptOptions, PromptValidator, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };
+export { DerivePromptConfigContext, DerivePromptConfigNoDepsContext, DerivePromptConfigNoDepsOptions, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, PromptExecutionContext, PromptOptions, PromptValidator, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/dist/index.js

@@ -17,14 +17,22 @@ const derivedPromptConfigMarker = Symbol.for("@optique/prompt/derivedPromptConfi
 function isDerivedPromptConfig(config) {
 	return config != null && typeof config === "object" && derivedPromptConfigMarker in config && config[derivedPromptConfigMarker] === true;
 }
-function derivePromptConfig(source, resolver, options) {
+function derivePromptConfig(source, resolverOrOptions, options) {
+	if (typeof source === "function") return deriveNoDepsPromptConfig(source, resolverOrOptions);
+	const resolver = resolverOrOptions;
 	const isTuple = Array.isArray(source);
 	const dependencies = isTuple ? source : [source];
 	if (dependencies.length === 0) throw new TypeError("derivePromptConfig() requires at least one dependency source.");
 	const infos = dependencies.map(getDependencySourceInfo);
 	const singleDefault = options?.defaultValue;
 	const defaultValues = isTuple ? options?.defaultValues : singleDefault == null ? void 0 : () => [singleDefault()];
-	const resolve = isTuple ? (values$1, usedDefaults) => resolver(values$1, { usedDefaults }) : (values$1, usedDefaults) => resolver(values$1[0], { usedDefault: usedDefaults[0] });
+	const resolve = isTuple ? (values$1, usedDefaults, context) => resolver(values$1, {
+		usedDefaults,
+		...context
+	}) : (values$1, usedDefaults, context) => resolver(values$1[0], {
+		usedDefault: usedDefaults[0],
+		...context
+	});
 	return {
 		[derivedPromptConfigMarker]: true,
 		dependencies,
@@ -38,6 +46,19 @@ function derivePromptConfig(source, resolver, options) {
 		}
 	};
 }
+function deriveNoDepsPromptConfig(resolver, options) {
+	return {
+		[derivedPromptConfigMarker]: true,
+		dependencies: [],
+		dependencyIds: [],
+		dependencyLabels: [],
+		resolve: (_values, _usedDefaults, context) => resolver({ ...context }),
+		...options?.when == null ? {} : {
+			when: options.when,
+			otherwise: options.otherwise
+		}
+	};
+}
 function describeThrown(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -50,7 +71,7 @@ function describeThrown(error) {
 * (synchronous throws and rejections alike) become prompt failures so
 * the scheduler treats them like a cancelled prompt.
 */
-async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel) {
+async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel, signal) {
 	const runtime = exec?.dependencyRuntime;
 	const ids = config.dependencyIds;
 	if (runtime != null) {
@@ -101,7 +122,7 @@ async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel) {
 	try {
 		return {
 			ok: true,
-			config: await config.resolve(values$1, usedDefaults)
+			config: await config.resolve(values$1, usedDefaults, signal === void 0 ? {} : { signal })
 		};
 	} catch (error) {
 		return {
@@ -265,8 +286,7 @@ function createPromptAdapter(adapter) {
 			if (!isDerivedPromptConfig(config)) resolvedConfig = config;
 			else {
 				const source = promptedParser.dependencyMetadata?.source;
-				const resolved = await resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar);
-				throwIfPromptAborted(signal);
+				const resolved = await racePromptWorkWithAbort(signal, () => resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar, signal));
 				if (!resolved.ok) return {
 					success: false,
 					error: resolved.error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/prompt",
-  "version": "1.4.0-dev.2603",
+  "version": "1.4.0-dev.2604",
   "description": "Generic prompt adapter support for Optique",
   "keywords": [
     "CLI",
@@ -60,12 +60,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2603+d6d54fca"
+    "@optique/core": "1.4.0-dev.2604+e78868f4"
   },
   "devDependencies": {
-    "@optique/config": "1.4.0-dev.2603+d6d54fca",
-    "@optique/env": "1.4.0-dev.2603+d6d54fca",
-    "@optique/run": "1.4.0-dev.2603+d6d54fca",
+    "@optique/config": "1.4.0-dev.2604+e78868f4",
+    "@optique/env": "1.4.0-dev.2604+e78868f4",
+    "@optique/run": "1.4.0-dev.2604+e78868f4",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",