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

package/dist/modifiers.cjs

@@ -915,7 +915,37 @@ function makeFallbackDeferredValue(fallback, memoize) {
 }
 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.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

@@ -206,7 +206,7 @@ type DeferredValueSource = "specified" | "fallback";
  * @template C The handler-time context type passed to the fallback resolver.
  * @since 1.2.0
  */
-type DeferredValue<T, C = void> = ([C] extends [void] ? (() => T | Promise<T>) : ((ctx: C) => T | Promise<T>)) & {
+type DeferredValue<T, C = void> = ([C] extends [void] ? (() => T | Promise<T>) : [undefined] extends [C] ? ((ctx?: C) => T | Promise<T>) : ((ctx: C) => T | Promise<T>)) & {
   /**
    * Which branch produced this value: `"specified"` when the wrapped parser
    * produced a value, `"fallback"` when the fallback resolver was selected.
@@ -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
@@ -416,6 +419,7 @@ interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = un
    * @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>;

package/dist/modifiers.d.ts

@@ -206,7 +206,7 @@ type DeferredValueSource = "specified" | "fallback";
  * @template C The handler-time context type passed to the fallback resolver.
  * @since 1.2.0
  */
-type DeferredValue<T, C = void> = ([C] extends [void] ? (() => T | Promise<T>) : ((ctx: C) => T | Promise<T>)) & {
+type DeferredValue<T, C = void> = ([C] extends [void] ? (() => T | Promise<T>) : [undefined] extends [C] ? ((ctx?: C) => T | Promise<T>) : ((ctx: C) => T | Promise<T>)) & {
   /**
    * Which branch produced this value: `"specified"` when the wrapped parser
    * produced a value, `"fallback"` when the fallback resolver was selected.
@@ -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
@@ -416,6 +419,7 @@ interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = un
    * @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>;

package/dist/modifiers.js

@@ -915,7 +915,37 @@ function makeFallbackDeferredValue(fallback, memoize) {
 }
 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) => 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.2230",
+  "version": "1.2.0-dev.2234",
   "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.2230+7ac5924a"
+    "@optique/env": "1.2.0-dev.2234+763fcd3e"
   },
   "scripts": {
     "build": "tsdown",