@optique/core 0.10.0-dev.333 → 0.10.0-dev.342

package/dist/valueparser.d.ts

@@ -555,5 +555,1275 @@ interface UuidOptions {
  *          strings.
  */
 declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
+/**
+ * Options for creating a port parser that returns a JavaScript `number`.
+ */
+interface PortOptionsNumber {
+  /**
+   * The type of value to return.
+   * @default `"number"`
+   */
+  readonly type?: "number";
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `PORT`.
+   * @default `"PORT"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Minimum allowed port number (inclusive).
+   * @default `1`
+   */
+  readonly min?: number;
+  /**
+   * Maximum allowed port number (inclusive).
+   * @default `65535`
+   */
+  readonly max?: number;
+  /**
+   * If `true`, disallows well-known ports (1-1023).
+   * These ports typically require root/administrator privileges on most systems.
+   * @default `false`
+   */
+  readonly disallowWellKnown?: boolean;
+  /**
+   * Custom error messages for port parsing failures.
+   * @since 0.10.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid port number.
+     * Can be a static message or a function that receives the input.
+     * @since 0.10.0
+     */
+    invalidPort?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when port is below minimum value.
+     * Can be a static message or a function that receives the port and minimum.
+     * @since 0.10.0
+     */
+    belowMinimum?: Message | ((port: number, min: number) => Message);
+    /**
+     * Custom error message when port is above maximum value.
+     * Can be a static message or a function that receives the port and maximum.
+     * @since 0.10.0
+     */
+    aboveMaximum?: Message | ((port: number, max: number) => Message);
+    /**
+     * Custom error message when well-known port is used but disallowed.
+     * Can be a static message or a function that receives the port.
+     * @since 0.10.0
+     */
+    wellKnownNotAllowed?: Message | ((port: number) => Message);
+  };
+}
+/**
+ * Options for creating a port parser that returns a `bigint`.
+ */
+interface PortOptionsBigInt {
+  /**
+   * Must be set to `"bigint"` to create a `bigint` parser.
+   */
+  readonly type: "bigint";
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `PORT`.
+   * @default `"PORT"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Minimum allowed port number (inclusive).
+   * @default `1n`
+   */
+  readonly min?: bigint;
+  /**
+   * Maximum allowed port number (inclusive).
+   * @default `65535n`
+   */
+  readonly max?: bigint;
+  /**
+   * If `true`, disallows well-known ports (1-1023).
+   * These ports typically require root/administrator privileges on most systems.
+   * @default `false`
+   */
+  readonly disallowWellKnown?: boolean;
+  /**
+   * Custom error messages for port parsing failures.
+   * @since 0.10.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid port number.
+     * Can be a static message or a function that receives the input.
+     * @since 0.10.0
+     */
+    invalidPort?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when port is below minimum value.
+     * Can be a static message or a function that receives the port and minimum.
+     * @since 0.10.0
+     */
+    belowMinimum?: Message | ((port: bigint, min: bigint) => Message);
+    /**
+     * Custom error message when port is above maximum value.
+     * Can be a static message or a function that receives the port and maximum.
+     * @since 0.10.0
+     */
+    aboveMaximum?: Message | ((port: bigint, max: bigint) => Message);
+    /**
+     * Custom error message when well-known port is used but disallowed.
+     * Can be a static message or a function that receives the port.
+     * @since 0.10.0
+     */
+    wellKnownNotAllowed?: Message | ((port: bigint) => Message);
+  };
+}
+/**
+ * Creates a ValueParser for TCP/UDP port numbers that returns JavaScript numbers.
+ *
+ * @param options Configuration options for the port parser.
+ * @returns A {@link ValueParser} that parses strings into port numbers.
+ * @since 0.10.0
+ */
+declare function port(options?: PortOptionsNumber): ValueParser<"sync", number>;
+/**
+ * Creates a ValueParser for TCP/UDP port numbers that returns `bigint` values.
+ *
+ * @param options Configuration options for the `bigint` port parser.
+ * @returns A {@link ValueParser} that parses strings into `bigint` port values.
+ * @since 0.10.0
+ */
+declare function port(options: PortOptionsBigInt): ValueParser<"sync", bigint>;
+/**
+ * Options for the {@link ipv4} value parser.
+ *
+ * @since 0.10.0
+ */
+interface Ipv4Options {
+  /**
+   * The metavariable name for this parser.
+   *
+   * @default "IPV4"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, allows private IP ranges (10.0.0.0/8, 172.16.0.0/12,
+   * 192.168.0.0/16).
+   *
+   * @default true
+   */
+  readonly allowPrivate?: boolean;
+  /**
+   * If `true`, allows loopback addresses (127.0.0.0/8).
+   *
+   * @default true
+   */
+  readonly allowLoopback?: boolean;
+  /**
+   * If `true`, allows link-local addresses (169.254.0.0/16).
+   *
+   * @default true
+   */
+  readonly allowLinkLocal?: boolean;
+  /**
+   * If `true`, allows multicast addresses (224.0.0.0/4).
+   *
+   * @default true
+   */
+  readonly allowMulticast?: boolean;
+  /**
+   * If `true`, allows the broadcast address (255.255.255.255).
+   *
+   * @default true
+   */
+  readonly allowBroadcast?: boolean;
+  /**
+   * If `true`, allows the zero address (0.0.0.0).
+   *
+   * @default true
+   */
+  readonly allowZero?: boolean;
+  /**
+   * Custom error messages for IPv4 parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid IPv4 address.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidIpv4?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when private IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    privateNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when loopback IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    loopbackNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when link-local IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    linkLocalNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when multicast IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    multicastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when broadcast IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    broadcastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when zero IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    zeroNotAllowed?: Message | ((ip: string) => Message);
+  };
+}
+/**
+ * Creates a value parser for IPv4 addresses.
+ *
+ * This parser validates IPv4 addresses in dotted-decimal notation (e.g.,
+ * "192.168.1.1") and provides options to filter specific IP address types
+ * such as private, loopback, link-local, multicast, broadcast, and zero
+ * addresses.
+ *
+ * @param options The parser options.
+ * @returns A value parser for IPv4 addresses.
+ * @throws {TypeError} If the metavar is an empty string.
+ * @since 0.10.0
+ * @example
+ * ```typescript
+ * import { ipv4 } from "@optique/core/valueparser";
+ *
+ * // Basic IPv4 parser (allows all types)
+ * const address = ipv4();
+ *
+ * // Public IPs only (no private/loopback)
+ * const publicIp = ipv4({
+ *   allowPrivate: false,
+ *   allowLoopback: false
+ * });
+ *
+ * // Server binding (allow 0.0.0.0 and private IPs)
+ * const bindAddress = ipv4({
+ *   allowZero: true,
+ *   allowPrivate: true
+ * });
+ * ```
+ */
+declare function ipv4(options?: Ipv4Options): ValueParser<"sync", string>;
+/**
+ * Options for the {@link hostname} parser.
+ *
+ * @since 0.10.0
+ */
+interface HostnameOptions {
+  /**
+   * The metavariable name for this parser.
+   * @default "HOST"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, allows wildcard hostnames (e.g., "*.example.com").
+   * @default false
+   */
+  readonly allowWildcard?: boolean;
+  /**
+   * If `true`, allows underscores in hostnames.
+   * Technically invalid per RFC 1123, but commonly used in some contexts
+   * (e.g., service discovery records like "_service.example.com").
+   * @default false
+   */
+  readonly allowUnderscore?: boolean;
+  /**
+   * If `true`, allows "localhost" as a hostname.
+   * @default true
+   */
+  readonly allowLocalhost?: boolean;
+  /**
+   * Maximum hostname length in characters.
+   * @default 253
+   */
+  readonly maxLength?: number;
+  /**
+   * Custom error messages for hostname parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid hostname.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidHostname?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when wildcard hostname is used but disallowed.
+     * Can be a static message or a function that receives the hostname.
+     */
+    wildcardNotAllowed?: Message | ((hostname: string) => Message);
+    /**
+     * Custom error message when underscore is used but disallowed.
+     * Can be a static message or a function that receives the hostname.
+     */
+    underscoreNotAllowed?: Message | ((hostname: string) => Message);
+    /**
+     * Custom error message when "localhost" is used but disallowed.
+     * Can be a static message or a function that receives the hostname.
+     */
+    localhostNotAllowed?: Message | ((hostname: string) => Message);
+    /**
+     * Custom error message when hostname is too long.
+     * Can be a static message or a function that receives the hostname and max length.
+     */
+    tooLong?: Message | ((hostname: string, maxLength: number) => Message);
+  };
+}
+/**
+ * Creates a value parser for DNS hostnames.
+ *
+ * Validates hostnames according to RFC 1123:
+ * - Labels separated by dots
+ * - Each label: 1-63 characters
+ * - Labels can contain alphanumeric characters and hyphens
+ * - Labels cannot start or end with a hyphen
+ * - Total length ≤ 253 characters (default)
+ *
+ * @param options - Options for hostname validation.
+ * @returns A value parser for hostnames.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { hostname } from "@optique/core/valueparser";
+ *
+ * // Basic hostname parser
+ * const host = hostname();
+ *
+ * // Allow wildcards for certificate validation
+ * const domain = hostname({ allowWildcard: true });
+ *
+ * // Reject localhost
+ * const remoteHost = hostname({ allowLocalhost: false });
+ * ```
+ */
+declare function hostname(options?: HostnameOptions): ValueParser<"sync", string>;
+/**
+ * Options for the {@link email} parser.
+ *
+ * @since 0.10.0
+ */
+interface EmailOptions {
+  /**
+   * The metavariable name for this parser.
+   * @default "EMAIL"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, allows multiple email addresses separated by commas.
+   * Returns an array of email addresses.
+   * @default false
+   */
+  readonly allowMultiple?: boolean;
+  /**
+   * If `true`, allows display names in format "Name <email@example.com>".
+   * When enabled, returns the email address only (strips display name).
+   * @default false
+   */
+  readonly allowDisplayName?: boolean;
+  /**
+   * If `true`, converts email to lowercase.
+   * @default false
+   */
+  readonly lowercase?: boolean;
+  /**
+   * List of allowed email domains (e.g., ["example.com", "test.org"]).
+   * If specified, only emails from these domains are accepted.
+   */
+  readonly allowedDomains?: readonly string[];
+  /**
+   * Custom error messages for email parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid email address.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidEmail?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when email domain is not allowed.
+     * Can be a static message or a function that receives the email and allowed domains.
+     */
+    domainNotAllowed?: Message | ((email: string, allowedDomains: readonly string[]) => Message);
+  };
+}
+/**
+ * Creates a value parser for email addresses according to RFC 5322 (simplified).
+ *
+ * Validates email addresses with support for:
+ * - Simplified RFC 5322 addr-spec format (local-part@domain)
+ * - Local part: alphanumeric, dots, hyphens, underscores, plus signs
+ * - Quoted strings in local part
+ * - Display names (when `allowDisplayName` is enabled)
+ * - Multiple addresses (when `allowMultiple` is enabled)
+ * - Domain filtering (when `allowedDomains` is specified)
+ *
+ * @param options - Options for email validation.
+ * @returns A value parser for email addresses.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { email } from "@optique/core/valueparser";
+ *
+ * // Basic email parser
+ * const userEmail = email();
+ *
+ * // Multiple emails
+ * const recipients = email({ allowMultiple: true });
+ *
+ * // With display names
+ * const from = email({ allowDisplayName: true });
+ *
+ * // Restrict to company domains
+ * const workEmail = email({ allowedDomains: ["company.com"] });
+ * ```
+ */
+declare function email(options: EmailOptions & {
+  allowMultiple: true;
+}): ValueParser<"sync", readonly string[]>;
+declare function email(options?: EmailOptions): ValueParser<"sync", string>;
+/**
+ * Socket address value containing host and port.
+ *
+ * @since 0.10.0
+ */
+interface SocketAddressValue {
+  /**
+   * The host portion (hostname or IP address).
+   */
+  readonly host: string;
+  /**
+   * The port number.
+   */
+  readonly port: number;
+}
+/**
+ * Options for the {@link socketAddress} parser.
+ *
+ * @since 0.10.0
+ */
+interface SocketAddressOptions {
+  /**
+   * The metavariable name for this parser.
+   * @default "HOST:PORT"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Separator character(s) between host and port.
+   * @default ":"
+   */
+  readonly separator?: string;
+  /**
+   * Default port number if omitted from input.
+   * If not specified, port is required.
+   */
+  readonly defaultPort?: number;
+  /**
+   * If `true`, requires port to be specified in input
+   * (ignores `defaultPort`).
+   * @default false
+   */
+  readonly requirePort?: boolean;
+  /**
+   * Options for hostname/IP validation.
+   */
+  readonly host?: {
+    /**
+     * Type of host to accept.
+     * - `"hostname"`: Accept hostnames only
+     * - `"ip"`: Accept IP addresses only
+     * - `"both"`: Accept both hostnames and IP addresses
+     * @default "both"
+     */
+    readonly type?: "hostname" | "ip" | "both";
+    /**
+     * Options for hostname validation (when type is "hostname" or "both").
+     */
+    readonly hostname?: Omit<HostnameOptions, "metavar" | "errors">;
+    /**
+     * Options for IP validation (when type is "ip" or "both").
+     * Currently only supports IPv4.
+     */
+    readonly ip?: Omit<Ipv4Options, "metavar" | "errors">;
+  };
+  /**
+   * Options for port validation.
+   */
+  readonly port?: Omit<PortOptionsNumber, "metavar" | "errors" | "type">;
+  /**
+   * Custom error messages for socket address parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input format is invalid.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when port is missing but required.
+     * Can be a static message or a function that receives the input.
+     */
+    missingPort?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * 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)
+ * - Configurable host:port separator
+ * - Optional default port
+ * - Host type filtering (hostname only, IP only, or both)
+ * - Port range validation
+ *
+ * @param options - Options for socket address validation.
+ * @returns A value parser for socket addresses.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { socketAddress } from "@optique/core/valueparser";
+ *
+ * // Basic socket address parser
+ * const endpoint = socketAddress({ requirePort: true });
+ *
+ * // With default port
+ * const server = socketAddress({ defaultPort: 80 });
+ *
+ * // IP addresses only
+ * const bind = socketAddress({
+ *   defaultPort: 8080,
+ *   host: { type: "ip" }
+ * });
+ * ```
+ */
+declare function socketAddress(options?: SocketAddressOptions): ValueParser<"sync", SocketAddressValue>;
+/**
+ * Port range value with number type.
+ *
+ * @since 0.10.0
+ */
+interface PortRangeValueNumber {
+  /**
+   * Starting port number (inclusive).
+   */
+  readonly start: number;
+  /**
+   * Ending port number (inclusive).
+   */
+  readonly end: number;
+}
+/**
+ * Port range value with bigint type.
+ *
+ * @since 0.10.0
+ */
+interface PortRangeValueBigInt {
+  /**
+   * Starting port number (inclusive).
+   */
+  readonly start: bigint;
+  /**
+   * Ending port number (inclusive).
+   */
+  readonly end: bigint;
+}
+/**
+ * Options for the {@link portRange} parser that returns number values.
+ *
+ * @since 0.10.0
+ */
+interface PortRangeOptionsNumber {
+  /**
+   * The type of values to return.
+   * @default "number"
+   */
+  readonly type?: "number";
+  /**
+   * The metavariable name for this parser.
+   * @default "PORT-PORT"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Separator character(s) between start and end ports.
+   * @default "-"
+   */
+  readonly separator?: string;
+  /**
+   * Minimum allowed port number (inclusive).
+   * Applied to both start and end ports.
+   * @default 1
+   */
+  readonly min?: number;
+  /**
+   * Maximum allowed port number (inclusive).
+   * Applied to both start and end ports.
+   * @default 65535
+   */
+  readonly max?: number;
+  /**
+   * If `true`, disallows well-known ports (1-1023).
+   * Applied to both start and end ports.
+   * @default false
+   */
+  readonly disallowWellKnown?: boolean;
+  /**
+   * If `true`, allows single port without range (e.g., "8080").
+   * The result will have `start === end`.
+   * @default false
+   */
+  readonly allowSingle?: boolean;
+  /**
+   * Custom error messages for port range parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input format is invalid.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when start port is greater than end port.
+     * Can be a static message or a function that receives start and end.
+     */
+    invalidRange?: Message | ((start: number, end: number) => Message);
+    /**
+     * Custom error message when port is invalid.
+     * Inherited from PortOptions.
+     */
+    invalidPort?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when port is below minimum.
+     * Inherited from PortOptions.
+     */
+    belowMinimum?: Message | ((port: number, min: number) => Message);
+    /**
+     * Custom error message when port is above maximum.
+     * Inherited from PortOptions.
+     */
+    aboveMaximum?: Message | ((port: number, max: number) => Message);
+    /**
+     * Custom error message when well-known port is not allowed.
+     * Inherited from PortOptions.
+     */
+    wellKnownNotAllowed?: Message | ((port: number) => Message);
+  };
+}
+/**
+ * Options for the {@link portRange} parser that returns bigint values.
+ *
+ * @since 0.10.0
+ */
+interface PortRangeOptionsBigInt {
+  /**
+   * Must be set to "bigint" to create a bigint parser.
+   */
+  readonly type: "bigint";
+  /**
+   * The metavariable name for this parser.
+   * @default "PORT-PORT"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Separator character(s) between start and end ports.
+   * @default "-"
+   */
+  readonly separator?: string;
+  /**
+   * Minimum allowed port number (inclusive).
+   * Applied to both start and end ports.
+   * @default 1n
+   */
+  readonly min?: bigint;
+  /**
+   * Maximum allowed port number (inclusive).
+   * Applied to both start and end ports.
+   * @default 65535n
+   */
+  readonly max?: bigint;
+  /**
+   * If `true`, disallows well-known ports (1-1023).
+   * Applied to both start and end ports.
+   * @default false
+   */
+  readonly disallowWellKnown?: boolean;
+  /**
+   * If `true`, allows single port without range (e.g., "8080").
+   * The result will have `start === end`.
+   * @default false
+   */
+  readonly allowSingle?: boolean;
+  /**
+   * Custom error messages for port range parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input format is invalid.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when start port is greater than end port.
+     * Can be a static message or a function that receives start and end.
+     */
+    invalidRange?: Message | ((start: bigint, end: bigint) => Message);
+    /**
+     * Custom error message when port is invalid.
+     * Inherited from PortOptions.
+     */
+    invalidPort?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when port is below minimum.
+     * Inherited from PortOptions.
+     */
+    belowMinimum?: Message | ((port: bigint, min: bigint) => Message);
+    /**
+     * Custom error message when port is above maximum.
+     * Inherited from PortOptions.
+     */
+    aboveMaximum?: Message | ((port: bigint, max: bigint) => Message);
+    /**
+     * Custom error message when well-known port is not allowed.
+     * Inherited from PortOptions.
+     */
+    wellKnownNotAllowed?: Message | ((port: bigint) => Message);
+  };
+}
+/**
+ * Creates a value parser for port ranges (e.g., "8000-8080").
+ *
+ * Validates port ranges with support for:
+ * - Custom separator between start and end ports
+ * - Single port mode (when `allowSingle` is enabled)
+ * - Port number or bigint types
+ * - Min/max constraints
+ * - Well-known port restrictions
+ *
+ * @param options - Options for port range validation.
+ * @returns A value parser for port ranges.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { portRange } from "@optique/core/valueparser";
+ *
+ * // Basic port range parser
+ * const range = portRange();
+ *
+ * // Allow single port
+ * const flexible = portRange({ allowSingle: true });
+ *
+ * // Non-privileged ports only
+ * const safe = portRange({ min: 1024 });
+ *
+ * // Using bigint type
+ * const bigRange = portRange({ type: "bigint" });
+ * ```
+ */
+declare function portRange(options: PortRangeOptionsBigInt): ValueParser<"sync", PortRangeValueBigInt>;
+declare function portRange(options?: PortRangeOptionsNumber): ValueParser<"sync", PortRangeValueNumber>;
+/**
+ * Options for the {@link macAddress} parser.
+ *
+ * @since 0.10.0
+ */
+interface MacAddressOptions {
+  /**
+   * The metavariable name for this parser.
+   * @default "MAC"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Separator format to accept.
+   * - `":"`: Colon-separated (e.g., `00:1A:2B:3C:4D:5E`)
+   * - `"-"`: Hyphen-separated (e.g., `00-1A-2B-3C-4D-5E`)
+   * - `"."`: Dot-separated (e.g., `001A.2B3C.4D5E` - Cisco format)
+   * - `"none"`: No separator (e.g., `001A2B3C4D5E`)
+   * - `"any"`: Accept any of the above formats
+   * @default "any"
+   */
+  readonly separator?: ":" | "-" | "." | "none" | "any";
+  /**
+   * Case for the output.
+   * - `"preserve"`: Keep input case
+   * - `"upper"`: Convert to uppercase
+   * - `"lower"`: Convert to lowercase
+   * @default "preserve"
+   */
+  readonly case?: "preserve" | "upper" | "lower";
+  /**
+   * Output separator format.
+   * If not specified, uses the input separator (or ":" for "any").
+   * @default undefined (uses input format)
+   */
+  readonly outputSeparator?: ":" | "-" | "." | "none";
+  /**
+   * Custom error messages for MAC address parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid MAC address.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidMacAddress?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser for MAC (Media Access Control) addresses.
+ *
+ * Validates MAC-48 addresses (6 octets, 12 hex digits) in various formats:
+ * - Colon-separated: `00:1A:2B:3C:4D:5E`
+ * - Hyphen-separated: `00-1A-2B-3C-4D-5E`
+ * - Dot-separated (Cisco): `001A.2B3C.4D5E`
+ * - No separator: `001A2B3C4D5E`
+ *
+ * Returns the MAC address as a formatted string according to `case` and
+ * `outputSeparator` options.
+ *
+ * @param options Configuration options for the MAC address parser.
+ * @returns A parser that validates MAC addresses and returns formatted strings.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { macAddress } from "@optique/core/valueparser";
+ *
+ * // Accept any format
+ * const mac = macAddress();
+ *
+ * // Normalize to uppercase colon-separated
+ * const normalizedMac = macAddress({
+ *   outputSeparator: ":",
+ *   case: "upper"
+ * });
+ * ```
+ */
+declare function macAddress(options?: MacAddressOptions): ValueParser<"sync", string>;
+/**
+ * Options for {@link domain} parser.
+ *
+ * @since 0.10.0
+ */
+interface DomainOptions {
+  /**
+   * The metavariable name for this parser.
+   *
+   * @default "DOMAIN"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, allows subdomains (e.g., "www.example.com").
+   * If `false`, only accepts root domains (e.g., "example.com").
+   *
+   * @default true
+   */
+  readonly allowSubdomains?: boolean;
+  /**
+   * List of allowed top-level domains (e.g., ["com", "org", "net"]).
+   * If specified, only domains with these TLDs are accepted.
+   */
+  readonly allowedTLDs?: readonly string[];
+  /**
+   * Minimum number of domain labels (parts separated by dots).
+   *
+   * @default 2
+   */
+  readonly minLabels?: number;
+  /**
+   * If `true`, converts domain to lowercase.
+   *
+   * @default false
+   */
+  readonly lowercase?: boolean;
+  /**
+   * Custom error messages for domain parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid domain.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidDomain?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when subdomains are not allowed.
+     * Can be a static message or a function that receives the domain.
+     */
+    subdomainsNotAllowed?: Message | ((domain: string) => Message);
+    /**
+     * Custom error message when TLD is not allowed.
+     * Can be a static message or a function that receives the TLD
+     * and allowed TLDs.
+     */
+    tldNotAllowed?: Message | ((tld: string, allowedTLDs: readonly string[]) => Message);
+    /**
+     * Custom error message when domain has too few labels.
+     * Can be a static message or a function that receives the domain
+     * and minimum labels.
+     */
+    tooFewLabels?: Message | ((domain: string, minLabels: number) => Message);
+  };
+}
+/**
+ * Creates a value parser for domain names.
+ *
+ * Validates domain names according to RFC 1035 with configurable options for
+ * subdomain filtering, TLD restrictions, minimum label requirements, and case
+ * normalization.
+ *
+ * @param options Parser options for domain validation.
+ * @returns A parser that accepts valid domain names as strings.
+ *
+ * @example
+ * ``` typescript
+ * import { option } from "@optique/core/primitives";
+ * import { domain } from "@optique/core/valueparser";
+ *
+ * // Accept any valid domain
+ * option("--domain", domain())
+ *
+ * // Root domains only (no subdomains)
+ * option("--root", domain({ allowSubdomains: false }))
+ *
+ * // Restrict to specific TLDs
+ * option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+ *
+ * // Normalize to lowercase
+ * option("--domain", domain({ lowercase: true }))
+ * ```
+ *
+ * @since 0.10.0
+ */
+declare function domain(options?: DomainOptions & {
+  readonly metavar?: NonEmptyString;
+}): ValueParser<"sync", string>;
+/**
+ * Options for configuring the IPv6 address value parser.
+ *
+ * @since 0.10.0
+ */
+interface Ipv6Options {
+  /**
+   * The metavariable name for this parser.
+   *
+   * @default `"IPV6"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, allows loopback address (::1).
+   *
+   * @default `true`
+   */
+  readonly allowLoopback?: boolean;
+  /**
+   * If `true`, allows link-local addresses (fe80::/10).
+   *
+   * @default `true`
+   */
+  readonly allowLinkLocal?: boolean;
+  /**
+   * If `true`, allows unique local addresses (fc00::/7).
+   *
+   * @default `true`
+   */
+  readonly allowUniqueLocal?: boolean;
+  /**
+   * If `true`, allows multicast addresses (ff00::/8).
+   *
+   * @default `true`
+   */
+  readonly allowMulticast?: boolean;
+  /**
+   * If `true`, allows the zero address (::).
+   *
+   * @default `true`
+   */
+  readonly allowZero?: boolean;
+  /**
+   * Custom error messages for IPv6 parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid IPv6 address.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidIpv6?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when loopback IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    loopbackNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when link-local IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    linkLocalNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when unique local IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    uniqueLocalNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when multicast IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    multicastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when zero IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    zeroNotAllowed?: Message | ((ip: string) => Message);
+  };
+}
+/**
+ * Creates a value parser for IPv6 addresses.
+ *
+ * Validates and normalizes IPv6 addresses to canonical form (lowercase,
+ * compressed using `::` notation where appropriate).
+ *
+ * @param options Configuration options for IPv6 validation.
+ * @returns A value parser that validates IPv6 addresses.
+ *
+ * @example
+ * ```typescript
+ * // Basic IPv6 parser
+ * option("--ipv6", ipv6())
+ *
+ * // Global unicast only (no link-local, no unique local)
+ * option("--public-ipv6", ipv6({
+ *   allowLinkLocal: false,
+ *   allowUniqueLocal: false
+ * }))
+ * ```
+ *
+ * @since 0.10.0
+ */
+declare function ipv6(options?: Ipv6Options): ValueParser<"sync", string>;
+/**
+ * Options for configuring the universal IP address value parser.
+ *
+ * @since 0.10.0
+ */
+interface IpOptions {
+  /**
+   * The metavariable name for this parser.
+   *
+   * @default `"IP"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * IP version to accept.
+   * - `4`: IPv4 only
+   * - `6`: IPv6 only
+   * - `"both"`: Accept both IPv4 and IPv6
+   *
+   * @default `"both"`
+   */
+  readonly version?: 4 | 6 | "both";
+  /**
+   * Options for IPv4 validation (when version is 4 or "both").
+   */
+  readonly ipv4?: Omit<Ipv4Options, "metavar" | "errors">;
+  /**
+   * Options for IPv6 validation (when version is 6 or "both").
+   */
+  readonly ipv6?: Omit<Ipv6Options, "metavar" | "errors">;
+  /**
+   * Custom error messages for IP parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid IP address.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidIP?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when private IP is used but disallowed (IPv4).
+     * Can be a static message or a function that receives the IP.
+     */
+    privateNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when loopback IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    loopbackNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when link-local IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    linkLocalNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when multicast IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    multicastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when broadcast IP is used but disallowed (IPv4).
+     * Can be a static message or a function that receives the IP.
+     */
+    broadcastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when zero IP is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     */
+    zeroNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when unique local IP is used but disallowed (IPv6).
+     * Can be a static message or a function that receives the IP.
+     */
+    uniqueLocalNotAllowed?: Message | ((ip: string) => Message);
+  };
+}
+/**
+ * Creates a value parser that accepts both IPv4 and IPv6 addresses.
+ *
+ * By default, accepts both IPv4 and IPv6 addresses. Use the `version` option
+ * to restrict to a specific IP version.
+ *
+ * @param options Configuration options for IP validation.
+ * @returns A value parser that validates IP addresses.
+ *
+ * @example
+ * ```typescript
+ * // Accept both IPv4 and IPv6
+ * option("--ip", ip())
+ *
+ * // IPv4 only
+ * option("--ipv4", ip({ version: 4 }))
+ *
+ * // Public IPs only (both versions)
+ * option("--public-ip", ip({
+ *   ipv4: { allowPrivate: false, allowLoopback: false },
+ *   ipv6: { allowLinkLocal: false, allowUniqueLocal: false }
+ * }))
+ * ```
+ *
+ * @since 0.10.0
+ */
+declare function ip(options?: IpOptions): ValueParser<"sync", string>;
+/**
+ * Value representing a CIDR notation (IP address with prefix length).
+ *
+ * @since 0.10.0
+ */
+interface CidrValue {
+  /**
+   * The IP address portion (normalized).
+   */
+  readonly address: string;
+  /**
+   * The prefix length (0-32 for IPv4, 0-128 for IPv6).
+   */
+  readonly prefix: number;
+  /**
+   * IP version (4 or 6).
+   */
+  readonly version: 4 | 6;
+}
+/**
+ * Options for configuring the CIDR notation value parser.
+ *
+ * @since 0.10.0
+ */
+interface CidrOptions {
+  /**
+   * The metavariable name for this parser.
+   *
+   * @default `"CIDR"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * IP version to accept.
+   * - `4`: IPv4 CIDR only
+   * - `6`: IPv6 CIDR only
+   * - `"both"`: Accept both IPv4 and IPv6 CIDR
+   *
+   * @default `"both"`
+   */
+  readonly version?: 4 | 6 | "both";
+  /**
+   * Minimum allowed prefix length.
+   * For IPv4: 0-32, for IPv6: 0-128.
+   */
+  readonly minPrefix?: number;
+  /**
+   * Maximum allowed prefix length.
+   * For IPv4: 0-32, for IPv6: 0-128.
+   */
+  readonly maxPrefix?: number;
+  /**
+   * Options for IPv4 validation (when version is 4 or "both").
+   */
+  readonly ipv4?: Omit<Ipv4Options, "metavar" | "errors">;
+  /**
+   * Options for IPv6 validation (when version is 6 or "both").
+   */
+  readonly ipv6?: Omit<Ipv6Options, "metavar" | "errors">;
+  /**
+   * Custom error messages for CIDR parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid CIDR notation.
+     * Can be a static message or a function that receives the input.
+     */
+    invalidCidr?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when prefix length is invalid.
+     * Can be a static message or a function that receives the prefix and version.
+     */
+    invalidPrefix?: Message | ((prefix: number, version: 4 | 6) => Message);
+    /**
+     * Custom error message when prefix is below minimum.
+     * Can be a static message or a function that receives the prefix and minimum.
+     */
+    prefixBelowMinimum?: Message | ((prefix: number, min: number) => Message);
+    /**
+     * Custom error message when prefix is above maximum.
+     * Can be a static message or a function that receives the prefix and maximum.
+     */
+    prefixAboveMaximum?: Message | ((prefix: number, max: number) => Message);
+  };
+}
+/**
+ * Creates a value parser for CIDR notation (IP address with prefix length).
+ *
+ * Parses and validates CIDR notation like `192.168.0.0/24` or `2001:db8::/32`.
+ * Returns a structured object with the normalized IP address, prefix length,
+ * and IP version.
+ *
+ * @param options Configuration options for CIDR validation.
+ * @returns A value parser that validates CIDR notation.
+ *
+ * @example
+ * ```typescript
+ * // Accept both IPv4 and IPv6 CIDR
+ * option("--network", cidr())
+ *
+ * // IPv4 CIDR only with prefix constraints
+ * option("--subnet", cidr({
+ *   version: 4,
+ *   minPrefix: 16,
+ *   maxPrefix: 24
+ * }))
+ * ```
+ *
+ * @since 0.10.0
+ */
+declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };
+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, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };