@optique/core 1.0.0-dev.1499 → 1.0.0-dev.1500

package/dist/valueparser.d.cts

@@ -69,6 +69,21 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * @since 0.10.0
    */
   readonly choices?: readonly T[];
+  /**
+   * A type-appropriate default value used as a stand-in during deferred
+   * prompt resolution.  When an interactive prompt is deferred during
+   * two-phase parsing, this value is used instead of an internal sentinel
+   * so that `map()` transforms and dynamic contexts always receive a valid
+   * value of type {@link T}.
+   *
+   * The placeholder does not need to be meaningful; it only needs to be
+   * a valid inhabitant of the result type that will not crash downstream
+   * transforms.  For example, `string()` uses `""`, `integer()` uses `0`,
+   * and `choice(["a", "b", "c"])` uses `"a"`.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder: T;
 }
 /**
  * Result type returned by {@link ValueParser#parse}.
@@ -83,12 +98,48 @@ type ValueParserResult<T> = {
   readonly success: true;
   /** The successfully parsed value of type {@link T}. */
   readonly value: T;
+  /**
+   * When `true`, indicates that the value is a placeholder stand-in for
+   * a deferred interactive prompt, not a real user-provided value.
+   * Combinators propagate this flag so that the two-phase parsing
+   * facade can strip deferred values before passing them to phase-two
+   * contexts.
+   *
+   * @since 1.0.0
+   */
+  readonly deferred?: true;
+  /**
+   * A recursive map describing which property keys in {@link value} hold
+   * deferred placeholder values.  Set by `object()`, `tuple()`, `merge()`,
+   * and other combinators.  Intentionally not propagated by `map()` because
+   * opaque transforms invalidate the inner key set.  Used by the two-phase
+   * facade to selectively replace only deferred fields with `undefined`
+   * while preserving non-deferred fields for phase-two context annotation
+   * collection.
+   *
+   * Each entry maps a property key to either `null` (the entire field is
+   * deferred) or another `DeferredMap` (the field is an object whose own
+   * sub-fields are partially deferred).
+   *
+   * @since 1.0.0
+   */
+  readonly deferredKeys?: DeferredMap;
 } | {
   /** Indicates that the parsing operation failed. */
   readonly success: false;
   /** The error message describing why the parsing failed. */
   readonly error: Message;
 };
+/**
+ * A recursive map that tracks which fields in a parsed object hold deferred
+ * placeholder values.  Each entry maps a property key to either `null`
+ * (the field is fully deferred and should be replaced with `undefined`)
+ * or another `DeferredMap` (the field is partially deferred — recurse into
+ * its sub-fields).
+ *
+ * @since 1.0.0
+ */
+type DeferredMap = ReadonlyMap<PropertyKey, DeferredMap | null>;
 /**
  * Options for creating a string parser.
  */
@@ -112,6 +163,14 @@ interface StringOptions {
    * to validate patterns before use.
    */
   readonly pattern?: RegExp;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `""` when a `pattern` constraint or downstream
+   * `map()` transform requires a non-empty or specially shaped string.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * Custom error messages for various string parsing failures.
    * @since 0.5.0
@@ -193,6 +252,9 @@ type ChoiceOptions = ChoiceOptionsString;
  * A predicate function that checks if an object is a {@link ValueParser}.
  * @param object The object to check.
  * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
+ * @throws {TypeError} If the object looks like a value parser (has `$mode`,
+ *   `metavar`, `parse`, and `format`) but is missing the required
+ *   `placeholder` property.
  */
 declare function isValueParser<M extends Mode, T>(object: unknown): object is ValueParser<M, T>;
 /**
@@ -304,6 +366,14 @@ interface IntegerOptionsNumber {
    * no maximum is enforced.
    */
   readonly max?: number;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `0` when `min`/`max` constraints or downstream
+   * `map()` transforms require a specific value.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: number;
   /**
    * Custom error messages for integer parsing failures.
    * @since 0.5.0
@@ -362,6 +432,14 @@ interface IntegerOptionsBigInt {
    * no maximum is enforced.
    */
   readonly max?: bigint;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `0n` when `min`/`max` constraints or downstream
+   * `map()` transforms require a specific value.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: bigint;
   /**
    * Custom error messages for bigint integer parsing failures.
    * @since 0.5.0
@@ -436,6 +514,14 @@ interface FloatOptions {
    * @default `false`
    */
   readonly allowInfinity?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `0` when `min`/`max` constraints or downstream
+   * `map()` transforms require a specific value.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: number;
   /**
    * Custom error messages for float parsing failures.
    * @since 0.5.0
@@ -689,6 +775,13 @@ interface PortOptionsNumber {
    * @default `false`
    */
   readonly disallowWellKnown?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Defaults to `min` (which itself defaults to `1`).
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: number;
   /**
    * Custom error messages for port parsing failures.
    * @since 0.10.0
@@ -751,6 +844,13 @@ interface PortOptionsBigInt {
    * @default `false`
    */
   readonly disallowWellKnown?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Defaults to `min` (which itself defaults to `1n`).
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: bigint;
   /**
    * Custom error messages for port parsing failures.
    * @since 0.10.0
@@ -949,6 +1049,13 @@ interface HostnameOptions {
    * @default true
    */
   readonly allowLocalhost?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override when `allowLocalhost` or other constraints reject the default.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * Maximum hostname length in characters.
    * @default 253
@@ -1054,6 +1161,13 @@ interface EmailOptions {
    * If specified, only emails from these domains are accepted.
    */
   readonly allowedDomains?: readonly string[];
+  /**
+   * Override the default placeholder value used for deferred parsing.
+   * When not specified, the placeholder is derived from the first entry in
+   * {@link allowedDomains} (or `"example.com"` when no domains are set).
+   * @since 1.0.0
+   */
+  readonly placeholder?: string | readonly string[];
   /**
    * Custom error messages for email parsing failures.
    */
@@ -1086,6 +1200,8 @@ interface EmailOptions {
  * @throws {TypeError} If any `allowedDomains` entry is not a string, has
  *   leading/trailing whitespace, starts with `"@"`, is empty, lacks a dot,
  *   has invalid hostname label syntax, or is an IPv4-like dotted-quad.
+ * @throws {TypeError} If `placeholder` type does not match `allowMultiple`
+ *   mode (string for single, array for multiple).
  * @since 0.10.0
  *
  * @example
@@ -1574,6 +1690,14 @@ interface DomainOptions {
    * @since 1.0.0
    */
   readonly maxLength?: number;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override when `allowedTlds`, `minLabels`, or other constraints
+   * reject the default `"example.com"`.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * If `true`, converts domain to lowercase.
    *
@@ -2015,4 +2139,4 @@ interface CidrOptions {
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -69,6 +69,21 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * @since 0.10.0
    */
   readonly choices?: readonly T[];
+  /**
+   * A type-appropriate default value used as a stand-in during deferred
+   * prompt resolution.  When an interactive prompt is deferred during
+   * two-phase parsing, this value is used instead of an internal sentinel
+   * so that `map()` transforms and dynamic contexts always receive a valid
+   * value of type {@link T}.
+   *
+   * The placeholder does not need to be meaningful; it only needs to be
+   * a valid inhabitant of the result type that will not crash downstream
+   * transforms.  For example, `string()` uses `""`, `integer()` uses `0`,
+   * and `choice(["a", "b", "c"])` uses `"a"`.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder: T;
 }
 /**
  * Result type returned by {@link ValueParser#parse}.
@@ -83,12 +98,48 @@ type ValueParserResult<T> = {
   readonly success: true;
   /** The successfully parsed value of type {@link T}. */
   readonly value: T;
+  /**
+   * When `true`, indicates that the value is a placeholder stand-in for
+   * a deferred interactive prompt, not a real user-provided value.
+   * Combinators propagate this flag so that the two-phase parsing
+   * facade can strip deferred values before passing them to phase-two
+   * contexts.
+   *
+   * @since 1.0.0
+   */
+  readonly deferred?: true;
+  /**
+   * A recursive map describing which property keys in {@link value} hold
+   * deferred placeholder values.  Set by `object()`, `tuple()`, `merge()`,
+   * and other combinators.  Intentionally not propagated by `map()` because
+   * opaque transforms invalidate the inner key set.  Used by the two-phase
+   * facade to selectively replace only deferred fields with `undefined`
+   * while preserving non-deferred fields for phase-two context annotation
+   * collection.
+   *
+   * Each entry maps a property key to either `null` (the entire field is
+   * deferred) or another `DeferredMap` (the field is an object whose own
+   * sub-fields are partially deferred).
+   *
+   * @since 1.0.0
+   */
+  readonly deferredKeys?: DeferredMap;
 } | {
   /** Indicates that the parsing operation failed. */
   readonly success: false;
   /** The error message describing why the parsing failed. */
   readonly error: Message;
 };
+/**
+ * A recursive map that tracks which fields in a parsed object hold deferred
+ * placeholder values.  Each entry maps a property key to either `null`
+ * (the field is fully deferred and should be replaced with `undefined`)
+ * or another `DeferredMap` (the field is partially deferred — recurse into
+ * its sub-fields).
+ *
+ * @since 1.0.0
+ */
+type DeferredMap = ReadonlyMap<PropertyKey, DeferredMap | null>;
 /**
  * Options for creating a string parser.
  */
@@ -112,6 +163,14 @@ interface StringOptions {
    * to validate patterns before use.
    */
   readonly pattern?: RegExp;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `""` when a `pattern` constraint or downstream
+   * `map()` transform requires a non-empty or specially shaped string.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * Custom error messages for various string parsing failures.
    * @since 0.5.0
@@ -193,6 +252,9 @@ type ChoiceOptions = ChoiceOptionsString;
  * A predicate function that checks if an object is a {@link ValueParser}.
  * @param object The object to check.
  * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
+ * @throws {TypeError} If the object looks like a value parser (has `$mode`,
+ *   `metavar`, `parse`, and `format`) but is missing the required
+ *   `placeholder` property.
  */
 declare function isValueParser<M extends Mode, T>(object: unknown): object is ValueParser<M, T>;
 /**
@@ -304,6 +366,14 @@ interface IntegerOptionsNumber {
    * no maximum is enforced.
    */
   readonly max?: number;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `0` when `min`/`max` constraints or downstream
+   * `map()` transforms require a specific value.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: number;
   /**
    * Custom error messages for integer parsing failures.
    * @since 0.5.0
@@ -362,6 +432,14 @@ interface IntegerOptionsBigInt {
    * no maximum is enforced.
    */
   readonly max?: bigint;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `0n` when `min`/`max` constraints or downstream
+   * `map()` transforms require a specific value.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: bigint;
   /**
    * Custom error messages for bigint integer parsing failures.
    * @since 0.5.0
@@ -436,6 +514,14 @@ interface FloatOptions {
    * @default `false`
    */
   readonly allowInfinity?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `0` when `min`/`max` constraints or downstream
+   * `map()` transforms require a specific value.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: number;
   /**
    * Custom error messages for float parsing failures.
    * @since 0.5.0
@@ -689,6 +775,13 @@ interface PortOptionsNumber {
    * @default `false`
    */
   readonly disallowWellKnown?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Defaults to `min` (which itself defaults to `1`).
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: number;
   /**
    * Custom error messages for port parsing failures.
    * @since 0.10.0
@@ -751,6 +844,13 @@ interface PortOptionsBigInt {
    * @default `false`
    */
   readonly disallowWellKnown?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Defaults to `min` (which itself defaults to `1n`).
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: bigint;
   /**
    * Custom error messages for port parsing failures.
    * @since 0.10.0
@@ -949,6 +1049,13 @@ interface HostnameOptions {
    * @default true
    */
   readonly allowLocalhost?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override when `allowLocalhost` or other constraints reject the default.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * Maximum hostname length in characters.
    * @default 253
@@ -1054,6 +1161,13 @@ interface EmailOptions {
    * If specified, only emails from these domains are accepted.
    */
   readonly allowedDomains?: readonly string[];
+  /**
+   * Override the default placeholder value used for deferred parsing.
+   * When not specified, the placeholder is derived from the first entry in
+   * {@link allowedDomains} (or `"example.com"` when no domains are set).
+   * @since 1.0.0
+   */
+  readonly placeholder?: string | readonly string[];
   /**
    * Custom error messages for email parsing failures.
    */
@@ -1086,6 +1200,8 @@ interface EmailOptions {
  * @throws {TypeError} If any `allowedDomains` entry is not a string, has
  *   leading/trailing whitespace, starts with `"@"`, is empty, lacks a dot,
  *   has invalid hostname label syntax, or is an IPv4-like dotted-quad.
+ * @throws {TypeError} If `placeholder` type does not match `allowMultiple`
+ *   mode (string for single, array for multiple).
  * @since 0.10.0
  *
  * @example
@@ -1574,6 +1690,14 @@ interface DomainOptions {
    * @since 1.0.0
    */
   readonly maxLength?: number;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override when `allowedTlds`, `minLabels`, or other constraints
+   * reject the default `"example.com"`.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * If `true`, converts domain to lowercase.
    *
@@ -2015,4 +2139,4 @@ interface CidrOptions {
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };