@optique/core 1.1.0-dev.2148 → 1.1.0-dev.2160

package/dist/valueparser.d.cts

@@ -385,6 +385,130 @@ declare function checkEnumOption<T extends object>(options: T | undefined, key:
  *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
+interface KeyValueOptionsBase {
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate the expected key–value shape.
+   * @default `"KEY=VALUE"` with the configured separator.
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * The separator between key and value.
+   * @default `"="`
+   */
+  readonly separator?: string;
+  /**
+   * If `true`, accepts an empty key before the separator.
+   * @default `false`
+   */
+  readonly allowEmptyKey?: boolean;
+  /**
+   * If `true`, accepts an empty value after the separator.
+   * @default `true`
+   */
+  readonly allowEmptyValue?: boolean;
+  /**
+   * Chooses which separator occurrence is used when input contains the
+   * separator more than once.
+   * @default `"first"`
+   */
+  readonly split?: "first" | "last";
+  /**
+   * Custom error messages for key–value parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error when the input does not contain the separator.
+     */
+    readonly missingSeparator?: Message | ((input: string, separator: string) => Message);
+    /**
+     * Custom error when the key side is empty and empty keys are disabled.
+     */
+    readonly emptyKey?: Message | ((input: string) => Message);
+    /**
+     * Custom error when the value side is empty and empty values are disabled.
+     */
+    readonly emptyValue?: Message | ((input: string) => Message);
+    /**
+     * Custom error wrapper for key parser failures.
+     */
+    readonly invalidKey?: Message | ((error: Message) => Message);
+    /**
+     * Custom error wrapper for value parser failures.
+     */
+    readonly invalidValue?: Message | ((error: Message) => Message);
+  };
+}
+type IsDefaultString<T> = [T] extends [string] ? [string] extends [T] ? true : false : false;
+type KeyValueKeyOption<K> = IsDefaultString<K> extends true ? {
+  /**
+   * Parser used to validate and transform the key side.
+   * @default `string({ placeholder: "KEY" })`
+   */
+  readonly key?: ValueParser<"sync", K>;
+} : {
+  /**
+   * Parser used to validate and transform the key side.
+   * @default `string({ placeholder: "KEY" })`
+   */
+  readonly key: ValueParser<"sync", K>;
+};
+type KeyValueValueOption<V> = IsDefaultString<V> extends true ? {
+  /**
+   * Parser used to validate and transform the value side.
+   * @default `string()`
+   */
+  readonly value?: ValueParser<"sync", V>;
+} : {
+  /**
+   * Parser used to validate and transform the value side.
+   * @default `string()`
+   */
+  readonly value: ValueParser<"sync", V>;
+};
+/**
+ * Options for creating a {@link keyValue} parser.
+ *
+ * The default key and value parsers produce strings.  If {@link K} or
+ * {@link V} is anything other than the default `string` type, the
+ * corresponding child parser is required so the option object cannot promise
+ * a type that the default parser would not produce.
+ *
+ * @template K The parsed key type.
+ * @template V The parsed value type.
+ * @since 1.1.0
+ */
+type KeyValueOptions<K = string, V = string> = KeyValueOptionsBase & KeyValueKeyOption<K> & KeyValueValueOption<V>;
+type KeyValueOptionsInput = KeyValueOptionsBase & {
+  readonly key?: ValueParser<"sync", unknown>;
+  readonly value?: ValueParser<"sync", unknown>;
+};
+type KeyValueKeyType<Options> = Options extends {
+  readonly key: ValueParser<"sync", infer K>;
+} ? K : string;
+type KeyValueValueType<Options> = Options extends {
+  readonly value: ValueParser<"sync", infer V>;
+} ? V : string;
+type KeyValueResultType<Options> = Options extends KeyValueOptionsInput ? readonly [KeyValueKeyType<Options>, KeyValueValueType<Options>] : readonly [string, string];
+/**
+ * Creates a value parser for strings shaped like `KEY=VALUE`.
+ *
+ * The default parser splits on the first `=`, rejects empty keys, allows
+ * empty values, and returns a readonly `[key, value]` tuple.  Custom key and
+ * value parsers can narrow or transform either side while preserving the
+ * inferred tuple type.
+ *
+ * @template Options The option object type used to infer child parser results.
+ * @param options Configuration options for the key–value parser.
+ * @returns A sync value parser producing readonly key–value tuples.
+ * @throws {TypeError} If `separator` or `metavar` is empty, if
+ *   `allowEmptyKey` or `allowEmptyValue` is not a boolean, if `split` is not
+ *   `"first"` or `"last"`, or if `key` or `value` is not a sync value parser.
+ * @since 1.1.0
+ */
+declare function keyValue(): ValueParser<"sync", readonly [string, string]>;
+declare function keyValue<const Options extends KeyValueOptionsInput | undefined>(options: Options): ValueParser<"sync", KeyValueResultType<Options>>;
 /**
  * Options for creating an integer parser that returns a JavaScript `number`.
  *
@@ -1572,10 +1696,34 @@ interface SocketAddressOptions {
      */
     readonly hostname?: Omit<HostnameOptions, "metavar" | "errors">;
     /**
-     * Options for IP validation (when type is "ip" or "both").
-     * Currently only supports IPv4.
+     * IP version to accept when `type` is `"ip"` or `"both"`.
+     * - `4`: IPv4 only
+     * - `6`: IPv6 only
+     * - `"both"`: Accept both IPv4 and IPv6
+     *
+     * @default `"both"` unless only the legacy {@link ip} field is set, in
+     * which case the default is `4` to preserve IPv4-only compatibility.
+     * @since 1.1.0
+     */
+    readonly version?: 4 | 6 | "both";
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     * This is kept for backwards compatibility; prefer {@link ipv4} for
+     * new code.
      */
     readonly ip?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv4?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv6 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv6?: Omit<Ipv6Options, "metavar" | "errors">;
   };
   /**
    * Options for port validation.
@@ -1601,7 +1749,7 @@ interface SocketAddressOptions {
  * Creates a value parser for socket addresses in "host:port" format.
  *
  * Validates socket addresses with support for:
- * - Hostnames and IPv4 addresses (IPv6 support coming in future versions)
+ * - Hostnames, IPv4 addresses, and IPv6 addresses
  * - Configurable host:port separator
  * - Optional default port
  * - Host type filtering (hostname only, IP only, or both)
@@ -1612,6 +1760,8 @@ interface SocketAddressOptions {
  * @throws {TypeError} If `separator` is an empty string.
  * @throws {TypeError} If `separator` contains digit characters, since digits
  *   in the separator would cause ambiguous splitting of port input.
+ * @throws {TypeError} If `host.version` is provided but is not `4`, `6`, or
+ *   `"both"`.
  * @since 0.10.0
  *
  * @example
@@ -2908,4 +3058,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -385,6 +385,130 @@ declare function checkEnumOption<T extends object>(options: T | undefined, key:
  *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
+interface KeyValueOptionsBase {
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate the expected key–value shape.
+   * @default `"KEY=VALUE"` with the configured separator.
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * The separator between key and value.
+   * @default `"="`
+   */
+  readonly separator?: string;
+  /**
+   * If `true`, accepts an empty key before the separator.
+   * @default `false`
+   */
+  readonly allowEmptyKey?: boolean;
+  /**
+   * If `true`, accepts an empty value after the separator.
+   * @default `true`
+   */
+  readonly allowEmptyValue?: boolean;
+  /**
+   * Chooses which separator occurrence is used when input contains the
+   * separator more than once.
+   * @default `"first"`
+   */
+  readonly split?: "first" | "last";
+  /**
+   * Custom error messages for key–value parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error when the input does not contain the separator.
+     */
+    readonly missingSeparator?: Message | ((input: string, separator: string) => Message);
+    /**
+     * Custom error when the key side is empty and empty keys are disabled.
+     */
+    readonly emptyKey?: Message | ((input: string) => Message);
+    /**
+     * Custom error when the value side is empty and empty values are disabled.
+     */
+    readonly emptyValue?: Message | ((input: string) => Message);
+    /**
+     * Custom error wrapper for key parser failures.
+     */
+    readonly invalidKey?: Message | ((error: Message) => Message);
+    /**
+     * Custom error wrapper for value parser failures.
+     */
+    readonly invalidValue?: Message | ((error: Message) => Message);
+  };
+}
+type IsDefaultString<T> = [T] extends [string] ? [string] extends [T] ? true : false : false;
+type KeyValueKeyOption<K> = IsDefaultString<K> extends true ? {
+  /**
+   * Parser used to validate and transform the key side.
+   * @default `string({ placeholder: "KEY" })`
+   */
+  readonly key?: ValueParser<"sync", K>;
+} : {
+  /**
+   * Parser used to validate and transform the key side.
+   * @default `string({ placeholder: "KEY" })`
+   */
+  readonly key: ValueParser<"sync", K>;
+};
+type KeyValueValueOption<V> = IsDefaultString<V> extends true ? {
+  /**
+   * Parser used to validate and transform the value side.
+   * @default `string()`
+   */
+  readonly value?: ValueParser<"sync", V>;
+} : {
+  /**
+   * Parser used to validate and transform the value side.
+   * @default `string()`
+   */
+  readonly value: ValueParser<"sync", V>;
+};
+/**
+ * Options for creating a {@link keyValue} parser.
+ *
+ * The default key and value parsers produce strings.  If {@link K} or
+ * {@link V} is anything other than the default `string` type, the
+ * corresponding child parser is required so the option object cannot promise
+ * a type that the default parser would not produce.
+ *
+ * @template K The parsed key type.
+ * @template V The parsed value type.
+ * @since 1.1.0
+ */
+type KeyValueOptions<K = string, V = string> = KeyValueOptionsBase & KeyValueKeyOption<K> & KeyValueValueOption<V>;
+type KeyValueOptionsInput = KeyValueOptionsBase & {
+  readonly key?: ValueParser<"sync", unknown>;
+  readonly value?: ValueParser<"sync", unknown>;
+};
+type KeyValueKeyType<Options> = Options extends {
+  readonly key: ValueParser<"sync", infer K>;
+} ? K : string;
+type KeyValueValueType<Options> = Options extends {
+  readonly value: ValueParser<"sync", infer V>;
+} ? V : string;
+type KeyValueResultType<Options> = Options extends KeyValueOptionsInput ? readonly [KeyValueKeyType<Options>, KeyValueValueType<Options>] : readonly [string, string];
+/**
+ * Creates a value parser for strings shaped like `KEY=VALUE`.
+ *
+ * The default parser splits on the first `=`, rejects empty keys, allows
+ * empty values, and returns a readonly `[key, value]` tuple.  Custom key and
+ * value parsers can narrow or transform either side while preserving the
+ * inferred tuple type.
+ *
+ * @template Options The option object type used to infer child parser results.
+ * @param options Configuration options for the key–value parser.
+ * @returns A sync value parser producing readonly key–value tuples.
+ * @throws {TypeError} If `separator` or `metavar` is empty, if
+ *   `allowEmptyKey` or `allowEmptyValue` is not a boolean, if `split` is not
+ *   `"first"` or `"last"`, or if `key` or `value` is not a sync value parser.
+ * @since 1.1.0
+ */
+declare function keyValue(): ValueParser<"sync", readonly [string, string]>;
+declare function keyValue<const Options extends KeyValueOptionsInput | undefined>(options: Options): ValueParser<"sync", KeyValueResultType<Options>>;
 /**
  * Options for creating an integer parser that returns a JavaScript `number`.
  *
@@ -1572,10 +1696,34 @@ interface SocketAddressOptions {
      */
     readonly hostname?: Omit<HostnameOptions, "metavar" | "errors">;
     /**
-     * Options for IP validation (when type is "ip" or "both").
-     * Currently only supports IPv4.
+     * IP version to accept when `type` is `"ip"` or `"both"`.
+     * - `4`: IPv4 only
+     * - `6`: IPv6 only
+     * - `"both"`: Accept both IPv4 and IPv6
+     *
+     * @default `"both"` unless only the legacy {@link ip} field is set, in
+     * which case the default is `4` to preserve IPv4-only compatibility.
+     * @since 1.1.0
+     */
+    readonly version?: 4 | 6 | "both";
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     * This is kept for backwards compatibility; prefer {@link ipv4} for
+     * new code.
      */
     readonly ip?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv4?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv6 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv6?: Omit<Ipv6Options, "metavar" | "errors">;
   };
   /**
    * Options for port validation.
@@ -1601,7 +1749,7 @@ interface SocketAddressOptions {
  * Creates a value parser for socket addresses in "host:port" format.
  *
  * Validates socket addresses with support for:
- * - Hostnames and IPv4 addresses (IPv6 support coming in future versions)
+ * - Hostnames, IPv4 addresses, and IPv6 addresses
  * - Configurable host:port separator
  * - Optional default port
  * - Host type filtering (hostname only, IP only, or both)
@@ -1612,6 +1760,8 @@ interface SocketAddressOptions {
  * @throws {TypeError} If `separator` is an empty string.
  * @throws {TypeError} If `separator` contains digit characters, since digits
  *   in the separator would cause ambiguous splitting of port input.
+ * @throws {TypeError} If `host.version` is provided but is not `4`, `6`, or
+ *   `"both"`.
  * @since 0.10.0
  *
  * @example
@@ -2908,4 +3058,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };