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

package/dist/modifiers.cjs

@@ -913,9 +913,89 @@ 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;
-	return map(optional(map(parser, (value) => ({ value }))), (matched) => matched === void 0 ? makeFallbackDeferredValue(fallback, memoize) : makeSpecifiedDeferredValue(matched.value));
+	const base = optional(parser);
+	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 ? {
+			success: true,
+			value,
+			deferred: true
+		} : {
+			success: true,
+			value
+		};
+	}));
+	const descriptors = Object.getOwnPropertyDescriptors(base);
+	descriptors.complete = {
+		value: complete,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	};
+	descriptors.$valueType = {
+		value: [],
+		writable: true,
+		enumerable: true,
+		configurable: true
+	};
+	delete descriptors.normalizeValue;
+	delete descriptors.validateValue;
+	delete descriptors[fluentParserMarker];
+	const deferredParser = Object.create(Object.getPrototypeOf(base), descriptors);
+	return fluent(deferredParser);
 }
 /**
 * Checks whether a value is a {@link DeferredValue} produced by

package/dist/modifiers.d.cts

@@ -232,11 +232,14 @@ interface DeferredValueOptions {
  *
  * 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"`.  When the wrapped
- * parser did not produce a value, calling the function runs `fallback` and
- * `source` is `"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.
+ * 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
@@ -263,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}.
@@ -413,12 +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

@@ -232,11 +232,14 @@ interface DeferredValueOptions {
  *
  * 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"`.  When the wrapped
- * parser did not produce a value, calling the function runs `fallback` and
- * `source` is `"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.
+ * 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
@@ -263,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}.
@@ -413,12 +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,9 +913,89 @@ 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;
-	return map(optional(map(parser, (value) => ({ value }))), (matched) => matched === void 0 ? makeFallbackDeferredValue(fallback, memoize) : makeSpecifiedDeferredValue(matched.value));
+	const base = optional(parser);
+	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 ? {
+			success: true,
+			value,
+			deferred: true
+		} : {
+			success: true,
+			value
+		};
+	}));
+	const descriptors = Object.getOwnPropertyDescriptors(base);
+	descriptors.complete = {
+		value: complete,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	};
+	descriptors.$valueType = {
+		value: [],
+		writable: true,
+		enumerable: true,
+		configurable: true
+	};
+	delete descriptors.normalizeValue;
+	delete descriptors.validateValue;
+	delete descriptors[fluentParserMarker];
+	const deferredParser = Object.create(Object.getPrototypeOf(base), descriptors);
+	return fluent(deferredParser);
 }
 /**
 * Checks whether a value is a {@link DeferredValue} produced by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2232",
+  "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.2232+9fc28f44"
+    "@optique/env": "1.2.0-dev.2236+88a40b64"
   },
   "scripts": {
     "build": "tsdown",