@optique/core 1.0.0-dev.1178 → 1.0.0-dev.1197

package/dist/completion.cjs

@@ -47,12 +47,13 @@ function encodeExtensions(extensions) {
 * Replaces control characters that would corrupt shell completion protocols.
 * Shell completion formats use tabs as field delimiters and newlines as record
 * delimiters.  Null bytes are used as delimiters in zsh's format.
-* @param description The description string to sanitize.
-* @returns The sanitized description with control characters replaced by spaces.
+* This is used for both suggestion text and descriptions.
+* @param text The string to sanitize.
+* @returns The sanitized string with control characters replaced by spaces.
 * @internal
 */
-function sanitizeDescription(description) {
-	return description.replace(/[\t\n\r\0]/g, " ");
+function sanitizeForTransport(text) {
+	return text.replace(/[\t\n\r\0]/g, " ");
 }
 /**
 * The Bash shell completion generator.
@@ -287,7 +288,7 @@ complete -F _${programName} -- ${programName}
 		let i = 0;
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
-			if (suggestion.kind === "literal") yield `${suggestion.text}`;
+			if (suggestion.kind === "literal") yield sanitizeForTransport(suggestion.text);
 			else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
@@ -434,12 +435,12 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-			yield `${suggestion.text}\0${description}\0`;
+			const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+			yield `${sanitizeForTransport(suggestion.text)}\0${description}\0`;
 		} else {
 			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+			const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
 			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
@@ -724,12 +725,12 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1046,12 +1047,12 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1257,12 +1258,13 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+				const text = sanitizeForTransport(suggestion.text);
+				yield `${text}\t${text}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}

package/dist/completion.js

@@ -47,12 +47,13 @@ function encodeExtensions(extensions) {
 * Replaces control characters that would corrupt shell completion protocols.
 * Shell completion formats use tabs as field delimiters and newlines as record
 * delimiters.  Null bytes are used as delimiters in zsh's format.
-* @param description The description string to sanitize.
-* @returns The sanitized description with control characters replaced by spaces.
+* This is used for both suggestion text and descriptions.
+* @param text The string to sanitize.
+* @returns The sanitized string with control characters replaced by spaces.
 * @internal
 */
-function sanitizeDescription(description) {
-	return description.replace(/[\t\n\r\0]/g, " ");
+function sanitizeForTransport(text) {
+	return text.replace(/[\t\n\r\0]/g, " ");
 }
 /**
 * The Bash shell completion generator.
@@ -287,7 +288,7 @@ complete -F _${programName} -- ${programName}
 		let i = 0;
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
-			if (suggestion.kind === "literal") yield `${suggestion.text}`;
+			if (suggestion.kind === "literal") yield sanitizeForTransport(suggestion.text);
 			else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
@@ -434,12 +435,12 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-			yield `${suggestion.text}\0${description}\0`;
+			const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+			yield `${sanitizeForTransport(suggestion.text)}\0${description}\0`;
 		} else {
 			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+			const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
 			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
@@ -724,12 +725,12 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1046,12 +1047,12 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1257,12 +1258,13 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				const text = sanitizeForTransport(suggestion.text);
+				yield `${text}\t${text}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}

package/dist/doc.cjs

@@ -47,8 +47,9 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
-* @throws {TypeError} If `programName` or any non-empty section's title
-* contains a CR or LF character.
+* @throws {TypeError} If `programName` contains a CR or LF character, or if
+* any non-empty section's title is empty, whitespace-only, or contains a CR
+* or LF character.
 *
 * @example
 * ```typescript
@@ -113,7 +114,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (/[\r\n]/.test(section.title)) throw new TypeError("Section title must not contain newlines.");
+			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/doc.d.cts

@@ -263,8 +263,9 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
- * @throws {TypeError} If `programName` or any non-empty section's title
- * contains a CR or LF character.
+ * @throws {TypeError} If `programName` contains a CR or LF character, or if
+ * any non-empty section's title is empty, whitespace-only, or contains a CR
+ * or LF character.
  *
  * @example
  * ```typescript

package/dist/doc.d.ts

@@ -263,8 +263,9 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
- * @throws {TypeError} If `programName` or any non-empty section's title
- * contains a CR or LF character.
+ * @throws {TypeError} If `programName` contains a CR or LF character, or if
+ * any non-empty section's title is empty, whitespace-only, or contains a CR
+ * or LF character.
  *
  * @example
  * ```typescript

package/dist/doc.js

@@ -47,8 +47,9 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
-* @throws {TypeError} If `programName` or any non-empty section's title
-* contains a CR or LF character.
+* @throws {TypeError} If `programName` contains a CR or LF character, or if
+* any non-empty section's title is empty, whitespace-only, or contains a CR
+* or LF character.
 *
 * @example
 * ```typescript
@@ -113,7 +114,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (/[\r\n]/.test(section.title)) throw new TypeError("Section title must not contain newlines.");
+			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/index.cjs

@@ -19,6 +19,7 @@ exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.annotationKey = require_annotations.annotationKey;
 exports.argument = require_primitives.argument;
 exports.bash = require_completion.bash;
+exports.checkBooleanOption = require_valueparser.checkBooleanOption;
 exports.choice = require_valueparser.choice;
 exports.cidr = require_valueparser.cidr;
 exports.command = require_primitives.command;

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.js";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -7,9 +7,9 @@ import { DuplicateOptionError, concat, conditional, group, longestMatch, merge,
 import { formatDocPage } from "./doc.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
+import { checkBooleanOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/valueparser.cjs

@@ -113,7 +113,7 @@ function choice(choices, options = {}) {
 	}
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
-	if (stringOptions.caseInsensitive !== void 0 && typeof stringOptions.caseInsensitive !== "boolean") throw new TypeError(`Expected caseInsensitive to be a boolean, but got ${typeof stringOptions.caseInsensitive}: ${String(stringOptions.caseInsensitive)}.`);
+	checkBooleanOption(stringOptions, "caseInsensitive");
 	const caseInsensitive = stringOptions.caseInsensitive ?? false;
 	const normalizedValues = caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
 	if (caseInsensitive) {
@@ -159,6 +159,20 @@ function choice(choices, options = {}) {
 	};
 }
 /**
+* Validates that an option value, if present, is a boolean.
+* Throws a {@link TypeError} if the value is defined but not a boolean.
+*
+* @template T The type of the options object.
+* @param options The options object to check.
+* @param key The key of the option to validate.
+* @throws {TypeError} If the option value is defined but not a boolean.
+* @since 1.0.0
+*/
+function checkBooleanOption(options, key) {
+	const value = options?.[key];
+	if (value !== void 0 && typeof value !== "boolean") throw new TypeError(`Expected ${String(key)} to be a boolean, but got ${typeof value}: ${String(value)}.`);
+}
+/**
 * Expands a numeric string in scientific notation (e.g., `"1e+21"`,
 * `"1.5e-3"`, `".1e-6"`) into plain decimal form for normalization.
 * Used for both canonical `String(number)` output and user input.
@@ -871,7 +885,7 @@ function uuid(options = {}) {
 * @since 0.10.0
 */
 function port(options) {
-	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
+	checkBooleanOption(options, "disallowWellKnown");
 	if (options?.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
 	if (options?.type === "bigint") {
 		const metavar$1 = options.metavar ?? "PORT";
@@ -1133,6 +1147,8 @@ function ipv4(options) {
 *
 * @param options - Options for hostname validation.
 * @returns A value parser for hostnames.
+* @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+*   `allowLocalhost` is not a boolean.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @since 0.10.0
 *
@@ -1153,6 +1169,9 @@ function ipv4(options) {
 function hostname(options) {
 	const metavar = options?.metavar ?? "HOST";
 	require_nonempty.ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "allowWildcard");
+	checkBooleanOption(options, "allowUnderscore");
+	checkBooleanOption(options, "allowLocalhost");
 	const allowWildcard = options?.allowWildcard ?? false;
 	const allowUnderscore = options?.allowUnderscore ?? false;
 	const allowLocalhost = options?.allowLocalhost ?? true;
@@ -1614,8 +1633,8 @@ function socketAddress(options) {
 	};
 }
 function portRange(options) {
-	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
-	if (options?.allowSingle !== void 0 && typeof options.allowSingle !== "boolean") throw new TypeError(`Expected allowSingle to be a boolean, but got ${typeof options.allowSingle}: ${String(options.allowSingle)}.`);
+	checkBooleanOption(options, "disallowWellKnown");
+	checkBooleanOption(options, "allowSingle");
 	if (options?.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
 	const separator = options?.separator ?? "-";
 	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
@@ -1868,6 +1887,7 @@ function macAddress(options) {
 * @returns A parser that accepts valid domain names as strings.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
 * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
 *   contains dots, has leading/trailing whitespace, or is not a valid DNS
 *   label.
@@ -1896,6 +1916,8 @@ function macAddress(options) {
 */
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
+	checkBooleanOption(options, "allowSubdomains");
+	checkBooleanOption(options, "lowercase");
 	const allowSubdomains = options?.allowSubdomains ?? true;
 	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
 	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
@@ -2812,6 +2834,7 @@ function cidr(options) {
 }
 
 //#endregion
+exports.checkBooleanOption = checkBooleanOption;
 exports.choice = choice;
 exports.cidr = cidr;
 exports.domain = domain;

package/dist/valueparser.d.cts

@@ -233,6 +233,17 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
+/**
+ * Validates that an option value, if present, is a boolean.
+ * Throws a {@link TypeError} if the value is defined but not a boolean.
+ *
+ * @template T The type of the options object.
+ * @param options The options object to check.
+ * @param key The key of the option to validate.
+ * @throws {TypeError} If the option value is defined but not a boolean.
+ * @since 1.0.0
+ */
+declare function checkBooleanOption<T extends object>(options: T | undefined, key: keyof T): void;
 /**
  * Creates a {@link ValueParser} for strings.
  *
@@ -929,6 +940,8 @@ interface HostnameOptions {
  *
  * @param options - Options for hostname validation.
  * @returns A value parser for hostnames.
+ * @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+ *   `allowLocalhost` is not a boolean.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @since 0.10.0
  *
@@ -1548,6 +1561,7 @@ interface DomainOptions {
  * @returns A parser that accepts valid domain names as strings.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
  * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
  *   contains dots, has leading/trailing whitespace, or is not a valid DNS
  *   label.
@@ -1892,4 +1906,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, 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, 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, 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

@@ -233,6 +233,17 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
+/**
+ * Validates that an option value, if present, is a boolean.
+ * Throws a {@link TypeError} if the value is defined but not a boolean.
+ *
+ * @template T The type of the options object.
+ * @param options The options object to check.
+ * @param key The key of the option to validate.
+ * @throws {TypeError} If the option value is defined but not a boolean.
+ * @since 1.0.0
+ */
+declare function checkBooleanOption<T extends object>(options: T | undefined, key: keyof T): void;
 /**
  * Creates a {@link ValueParser} for strings.
  *
@@ -929,6 +940,8 @@ interface HostnameOptions {
  *
  * @param options - Options for hostname validation.
  * @returns A value parser for hostnames.
+ * @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+ *   `allowLocalhost` is not a boolean.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @since 0.10.0
  *
@@ -1548,6 +1561,7 @@ interface DomainOptions {
  * @returns A parser that accepts valid domain names as strings.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
  * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
  *   contains dots, has leading/trailing whitespace, or is not a valid DNS
  *   label.
@@ -1892,4 +1906,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, 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, 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, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/dist/valueparser.js

@@ -113,7 +113,7 @@ function choice(choices, options = {}) {
 	}
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
-	if (stringOptions.caseInsensitive !== void 0 && typeof stringOptions.caseInsensitive !== "boolean") throw new TypeError(`Expected caseInsensitive to be a boolean, but got ${typeof stringOptions.caseInsensitive}: ${String(stringOptions.caseInsensitive)}.`);
+	checkBooleanOption(stringOptions, "caseInsensitive");
 	const caseInsensitive = stringOptions.caseInsensitive ?? false;
 	const normalizedValues = caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
 	if (caseInsensitive) {
@@ -159,6 +159,20 @@ function choice(choices, options = {}) {
 	};
 }
 /**
+* Validates that an option value, if present, is a boolean.
+* Throws a {@link TypeError} if the value is defined but not a boolean.
+*
+* @template T The type of the options object.
+* @param options The options object to check.
+* @param key The key of the option to validate.
+* @throws {TypeError} If the option value is defined but not a boolean.
+* @since 1.0.0
+*/
+function checkBooleanOption(options, key) {
+	const value = options?.[key];
+	if (value !== void 0 && typeof value !== "boolean") throw new TypeError(`Expected ${String(key)} to be a boolean, but got ${typeof value}: ${String(value)}.`);
+}
+/**
 * Expands a numeric string in scientific notation (e.g., `"1e+21"`,
 * `"1.5e-3"`, `".1e-6"`) into plain decimal form for normalization.
 * Used for both canonical `String(number)` output and user input.
@@ -871,7 +885,7 @@ function uuid(options = {}) {
 * @since 0.10.0
 */
 function port(options) {
-	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
+	checkBooleanOption(options, "disallowWellKnown");
 	if (options?.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
 	if (options?.type === "bigint") {
 		const metavar$1 = options.metavar ?? "PORT";
@@ -1133,6 +1147,8 @@ function ipv4(options) {
 *
 * @param options - Options for hostname validation.
 * @returns A value parser for hostnames.
+* @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+*   `allowLocalhost` is not a boolean.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @since 0.10.0
 *
@@ -1153,6 +1169,9 @@ function ipv4(options) {
 function hostname(options) {
 	const metavar = options?.metavar ?? "HOST";
 	ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "allowWildcard");
+	checkBooleanOption(options, "allowUnderscore");
+	checkBooleanOption(options, "allowLocalhost");
 	const allowWildcard = options?.allowWildcard ?? false;
 	const allowUnderscore = options?.allowUnderscore ?? false;
 	const allowLocalhost = options?.allowLocalhost ?? true;
@@ -1614,8 +1633,8 @@ function socketAddress(options) {
 	};
 }
 function portRange(options) {
-	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
-	if (options?.allowSingle !== void 0 && typeof options.allowSingle !== "boolean") throw new TypeError(`Expected allowSingle to be a boolean, but got ${typeof options.allowSingle}: ${String(options.allowSingle)}.`);
+	checkBooleanOption(options, "disallowWellKnown");
+	checkBooleanOption(options, "allowSingle");
 	if (options?.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
 	const separator = options?.separator ?? "-";
 	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
@@ -1868,6 +1887,7 @@ function macAddress(options) {
 * @returns A parser that accepts valid domain names as strings.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
 * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
 *   contains dots, has leading/trailing whitespace, or is not a valid DNS
 *   label.
@@ -1896,6 +1916,8 @@ function macAddress(options) {
 */
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
+	checkBooleanOption(options, "allowSubdomains");
+	checkBooleanOption(options, "lowercase");
 	const allowSubdomains = options?.allowSubdomains ?? true;
 	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
 	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
@@ -2812,4 +2834,4 @@ function cidr(options) {
 }
 
 //#endregion
-export { choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { checkBooleanOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1178+6b5574a3",
+  "version": "1.0.0-dev.1197+8fa87a88",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",