@optique/core 1.2.0-dev.2234 → 1.2.0-dev.2236

package/dist/modifiers.cjs

@@ -913,10 +913,60 @@ function makeFallbackDeferredValue(fallback, memoize) {
 	};
 	return brandDeferredValue(call, "fallback");
 }
+/**
+* Wraps a parser so its value is resolved by the command handler instead of
+* during parsing.
+*
+* The parsed field becomes a {@link DeferredValue}: a value-producing function.
+* When the wrapped parser produced a value, calling the function returns that
+* value and {@link DeferredValue.source} is `"specified"`.  A value resolved
+* from a source such as `bindEnv()`/`bindConfig()` counts as produced.  When
+* the wrapped parser did not produce a value, calling the function runs
+* `fallback` and `source` is `"fallback"`.  Because a missing value is reported
+* as `undefined`, a wrapped parser that yields `undefined` is treated as having
+* produced no value and selects the fallback.  The fallback runs at handler
+* time, so its errors are handler errors rather than parser errors.  A value
+* that is specified but invalid still fails during parsing.
+*
+* Like {@link optional}, the wrapped parser keeps its place in usage and help;
+* only the result type changes.  The fallback context type `C` is inferred from
+* the `fallback` parameter.
+*
+* @example
+* ```typescript
+* const parser = object({
+*   serviceName: option("--service-name", string()),
+*   apiToken: deferredValue(
+*     option("--api-token", string()),
+*     ({ serviceName }: { readonly serviceName: string }) =>
+*       promptForApiToken(serviceName),
+*   ),
+* });
+*
+* const parsed = parse(parser, argv);
+* // The prompt only runs if this branch is reached.
+* const apiToken = await parsed.apiToken({
+*   serviceName: parsed.serviceName,
+* });
+* ```
+*
+* @template M The execution mode of the wrapped parser.
+* @template T The resolved value type.
+* @template S The state type of the wrapped parser.
+* @template C The handler-time context type, inferred from `fallback`.  A
+*             fallback without a parameter yields a no-argument
+*             {@link DeferredValue}; one whose parameter is optional or includes
+*             `undefined` stays callable with no argument.
+* @param parser The parser that reads the CLI value.
+* @param fallback A resolver run at handler time when no value was specified.
+* @param options Optional {@link DeferredValueOptions}.
+* @returns A parser whose value is a {@link DeferredValue}.
+* @since 1.2.0
+*/
 function deferredValue(parser, fallback, options) {
 	const memoize = options?.memoize ?? false;
 	const base = optional(parser);
-	const complete = (state, exec) => require_mode_dispatch.mapModeValue(base.mode, base.complete(state, exec), (result) => {
+	const complete = (state, exec) => require_mode_dispatch.wrapForMode(base.mode, require_mode_dispatch.mapModeValue(base.mode, base.complete(state, exec), (result) => {
 		if (!result.success) return result;
 		const value = result.value === void 0 ? makeFallbackDeferredValue(fallback, memoize) : makeSpecifiedDeferredValue(result.value);
 		return result.deferred ? {
@@ -927,7 +977,7 @@ function deferredValue(parser, fallback, options) {
 			success: true,
 			value
 		};
-	});
+	}));
 	const descriptors = Object.getOwnPropertyDescriptors(base);
 	descriptors.complete = {
 		value: complete,

package/dist/modifiers.d.cts

@@ -266,14 +266,17 @@ interface DeferredValueOptions {
  * @template M The execution mode of the wrapped parser.
  * @template T The resolved value type.
  * @template S The state type of the wrapped parser.
+ * @template C The handler-time context type, inferred from `fallback`.  A
+ *             fallback without a parameter yields a no-argument
+ *             {@link DeferredValue}; one whose parameter is optional or includes
+ *             `undefined` stays callable with no argument.
  * @param parser The parser that reads the CLI value.
  * @param fallback A resolver run at handler time when no value was specified.
  * @param options Optional {@link DeferredValueOptions}.
  * @returns A parser whose value is a {@link DeferredValue}.
  * @since 1.2.0
  */
-declare function deferredValue<M extends Mode, T, S>(parser: Parser<M, T, S>, fallback: () => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T>, [S] | undefined>;
-declare function deferredValue<M extends Mode, T, S, C>(parser: Parser<M, T, S>, fallback: (ctx: C) => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T, C>, [S] | undefined>;
+declare function deferredValue<M extends Mode, T, S, C = void>(parser: Parser<M, T, S>, fallback: (ctx: C) => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T, C>, [S] | undefined>;
 /**
  * Checks whether a value is a {@link DeferredValue} produced by
  * {@link deferredValue}.
@@ -416,13 +419,13 @@ interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = un
   /**
    * Defers this parser's value so the command handler resolves it.
    *
+   * @template C The handler-time context type, inferred from `fallback`.
    * @param fallback A resolver run at handler time when no value was specified.
    * @param options Optional {@link DeferredValueOptions}.
    * @returns A parser whose value is a {@link DeferredValue}.
    * @since 1.2.0
    */
-  deferredValue(fallback: () => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue>, [TState] | undefined>;
-  deferredValue<C>(fallback: (ctx: C) => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue, C>, [TState] | undefined>;
+  deferredValue<C = void>(fallback: (ctx: C) => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue, C>, [TState] | undefined>;
   /**
    * Allows this parser to match multiple times.
    *

package/dist/modifiers.d.ts

@@ -266,14 +266,17 @@ interface DeferredValueOptions {
  * @template M The execution mode of the wrapped parser.
  * @template T The resolved value type.
  * @template S The state type of the wrapped parser.
+ * @template C The handler-time context type, inferred from `fallback`.  A
+ *             fallback without a parameter yields a no-argument
+ *             {@link DeferredValue}; one whose parameter is optional or includes
+ *             `undefined` stays callable with no argument.
  * @param parser The parser that reads the CLI value.
  * @param fallback A resolver run at handler time when no value was specified.
  * @param options Optional {@link DeferredValueOptions}.
  * @returns A parser whose value is a {@link DeferredValue}.
  * @since 1.2.0
  */
-declare function deferredValue<M extends Mode, T, S>(parser: Parser<M, T, S>, fallback: () => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T>, [S] | undefined>;
-declare function deferredValue<M extends Mode, T, S, C>(parser: Parser<M, T, S>, fallback: (ctx: C) => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T, C>, [S] | undefined>;
+declare function deferredValue<M extends Mode, T, S, C = void>(parser: Parser<M, T, S>, fallback: (ctx: C) => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T, C>, [S] | undefined>;
 /**
  * Checks whether a value is a {@link DeferredValue} produced by
  * {@link deferredValue}.
@@ -416,13 +419,13 @@ interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = un
   /**
    * Defers this parser's value so the command handler resolves it.
    *
+   * @template C The handler-time context type, inferred from `fallback`.
    * @param fallback A resolver run at handler time when no value was specified.
    * @param options Optional {@link DeferredValueOptions}.
    * @returns A parser whose value is a {@link DeferredValue}.
    * @since 1.2.0
    */
-  deferredValue(fallback: () => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue>, [TState] | undefined>;
-  deferredValue<C>(fallback: (ctx: C) => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue, C>, [TState] | undefined>;
+  deferredValue<C = void>(fallback: (ctx: C) => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue, C>, [TState] | undefined>;
   /**
    * Allows this parser to match multiple times.
    *

package/dist/modifiers.js

@@ -913,10 +913,60 @@ function makeFallbackDeferredValue(fallback, memoize) {
 	};
 	return brandDeferredValue(call, "fallback");
 }
+/**
+* Wraps a parser so its value is resolved by the command handler instead of
+* during parsing.
+*
+* The parsed field becomes a {@link DeferredValue}: a value-producing function.
+* When the wrapped parser produced a value, calling the function returns that
+* value and {@link DeferredValue.source} is `"specified"`.  A value resolved
+* from a source such as `bindEnv()`/`bindConfig()` counts as produced.  When
+* the wrapped parser did not produce a value, calling the function runs
+* `fallback` and `source` is `"fallback"`.  Because a missing value is reported
+* as `undefined`, a wrapped parser that yields `undefined` is treated as having
+* produced no value and selects the fallback.  The fallback runs at handler
+* time, so its errors are handler errors rather than parser errors.  A value
+* that is specified but invalid still fails during parsing.
+*
+* Like {@link optional}, the wrapped parser keeps its place in usage and help;
+* only the result type changes.  The fallback context type `C` is inferred from
+* the `fallback` parameter.
+*
+* @example
+* ```typescript
+* const parser = object({
+*   serviceName: option("--service-name", string()),
+*   apiToken: deferredValue(
+*     option("--api-token", string()),
+*     ({ serviceName }: { readonly serviceName: string }) =>
+*       promptForApiToken(serviceName),
+*   ),
+* });
+*
+* const parsed = parse(parser, argv);
+* // The prompt only runs if this branch is reached.
+* const apiToken = await parsed.apiToken({
+*   serviceName: parsed.serviceName,
+* });
+* ```
+*
+* @template M The execution mode of the wrapped parser.
+* @template T The resolved value type.
+* @template S The state type of the wrapped parser.
+* @template C The handler-time context type, inferred from `fallback`.  A
+*             fallback without a parameter yields a no-argument
+*             {@link DeferredValue}; one whose parameter is optional or includes
+*             `undefined` stays callable with no argument.
+* @param parser The parser that reads the CLI value.
+* @param fallback A resolver run at handler time when no value was specified.
+* @param options Optional {@link DeferredValueOptions}.
+* @returns A parser whose value is a {@link DeferredValue}.
+* @since 1.2.0
+*/
 function deferredValue(parser, fallback, options) {
 	const memoize = options?.memoize ?? false;
 	const base = optional(parser);
-	const complete = (state, exec) => mapModeValue(base.mode, base.complete(state, exec), (result) => {
+	const complete = (state, exec) => wrapForMode(base.mode, mapModeValue(base.mode, base.complete(state, exec), (result) => {
 		if (!result.success) return result;
 		const value = result.value === void 0 ? makeFallbackDeferredValue(fallback, memoize) : makeSpecifiedDeferredValue(result.value);
 		return result.deferred ? {
@@ -927,7 +977,7 @@ function deferredValue(parser, fallback, options) {
 			success: true,
 			value
 		};
-	});
+	}));
 	const descriptors = Object.getOwnPropertyDescriptors(base);
 	descriptors.complete = {
 		value: complete,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2234",
+  "version": "1.2.0-dev.2236",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -208,7 +208,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2234+763fcd3e"
+    "@optique/env": "1.2.0-dev.2236+88a40b64"
   },
   "scripts": {
     "build": "tsdown",