@optique/core 1.2.0-dev.2298 → 1.2.0-dev.2302

package/dist/facade.cjs

@@ -539,7 +539,8 @@ function getHelpCommandContext(commandPath, args, helpIndex) {
 function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionOptionNames, completionCommandNames) {
 	if (failure.remainingArgs.length < 1) return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 	const hasConsumedPrefix = failure.consumedCount > 0;
 	const firstArg = failure.remainingArgs[0];
@@ -571,7 +572,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 		if (secondArg == null || isCompletionImmediatelyAfter || lastHelpVersion?.index === 1 && lastHelpVersion.kind === "version") return { type: "version" };
 		return {
 			type: "error",
-			error: failure.error
+			error: failure.error,
+			commandPath: failure.commandPath
 		};
 	}
 	let commandAction;
@@ -601,7 +603,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 	};
 	return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 }
 /**
@@ -949,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const norm = (c) => c === true ? {} : c;
@@ -1121,7 +1124,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const isSubcommandHelp = classified.commands.length > 0;
 						const isTopLevel = !isSubcommandHelp;
 						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
 							description: shouldOverride ? description ?? doc.description : doc.description,
@@ -1129,7 +1132,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
-						};
+						}, commandList, isTopLevel);
 						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
@@ -1190,7 +1193,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
@@ -1198,7 +1201,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: author ?? doc.author,
 							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
-						};
+						}, commandList, classified.commandPath.length < 1);
 						stderr(require_doc.formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
@@ -1295,6 +1298,42 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function maybeCollapseCommandList(doc, commandList, isTopLevel) {
+	if (commandList !== "top-level" || !isTopLevel) return doc;
+	return {
+		...doc,
+		sections: doc.sections.map((section) => ({
+			...section,
+			entries: collapseTopLevelCommandEntries(section.entries)
+		}))
+	};
+}
+function collapseTopLevelCommandEntries(entries) {
+	const collapsed = [];
+	const commandIndexes = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.term.type !== "command") {
+			collapsed.push(entry);
+			continue;
+		}
+		const topLevelName = getTopLevelCommandName(entry.term.name);
+		const existingIndex = commandIndexes.get(topLevelName);
+		const isTopLevel = entry.term.name === topLevelName;
+		if (existingIndex == null) {
+			commandIndexes.set(topLevelName, collapsed.length);
+			collapsed.push(isTopLevel ? entry : { term: {
+				...entry.term,
+				name: topLevelName
+			} });
+			continue;
+		}
+		if (isTopLevel) collapsed[existingIndex] = entry;
+	}
+	return collapsed;
+}
+function getTopLevelCommandName(name) {
+	return name.split(" ", 1)[0] ?? name;
+}
 /**
 * An error class used to indicate that the command line arguments
 * could not be parsed successfully.

package/dist/facade.d.cts

@@ -8,6 +8,17 @@ import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
 
+/**
+ * Controls how command lists are rendered in top-level help pages.
+ *
+ * - `"recursive"`: Shows the full flattened command list, including nested
+ *   leaf commands such as `remote add`.
+ * - `"top-level"`: Shows only first-level command names such as `remote`,
+ *   letting users drill down with `remote --help`.
+ *
+ * @since 1.2.0
+ */
+type CommandListMode = "recursive" | "top-level";
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -116,6 +127,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * How to render command lists in top-level help pages.
+   *
+   * Pass `"top-level"` to show only first-level commands in the command menu
+   * while keeping nested command help available through `<command> --help`.
+   *
+   * @default `"recursive"`
+   * @since 1.2.0
+   */
+  readonly commandList?: CommandListMode;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart
@@ -534,4 +555,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -8,6 +8,17 @@ import { Program } from "./program.js";
 
 //#region src/facade.d.ts
 
+/**
+ * Controls how command lists are rendered in top-level help pages.
+ *
+ * - `"recursive"`: Shows the full flattened command list, including nested
+ *   leaf commands such as `remote add`.
+ * - `"top-level"`: Shows only first-level command names such as `remote`,
+ *   letting users drill down with `remote --help`.
+ *
+ * @since 1.2.0
+ */
+type CommandListMode = "recursive" | "top-level";
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -116,6 +127,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * How to render command lists in top-level help pages.
+   *
+   * Pass `"top-level"` to show only first-level commands in the command menu
+   * while keeping nested command help available through `<command> --help`.
+   *
+   * @default `"recursive"`
+   * @since 1.2.0
+   */
+  readonly commandList?: CommandListMode;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart
@@ -534,4 +555,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -539,7 +539,8 @@ function getHelpCommandContext(commandPath, args, helpIndex) {
 function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionOptionNames, completionCommandNames) {
 	if (failure.remainingArgs.length < 1) return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 	const hasConsumedPrefix = failure.consumedCount > 0;
 	const firstArg = failure.remainingArgs[0];
@@ -571,7 +572,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 		if (secondArg == null || isCompletionImmediatelyAfter || lastHelpVersion?.index === 1 && lastHelpVersion.kind === "version") return { type: "version" };
 		return {
 			type: "error",
-			error: failure.error
+			error: failure.error,
+			commandPath: failure.commandPath
 		};
 	}
 	let commandAction;
@@ -601,7 +603,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 	};
 	return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 }
 /**
@@ -949,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const norm = (c) => c === true ? {} : c;
@@ -1121,7 +1124,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const isSubcommandHelp = classified.commands.length > 0;
 						const isTopLevel = !isSubcommandHelp;
 						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
 							description: shouldOverride ? description ?? doc.description : doc.description,
@@ -1129,7 +1132,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
-						};
+						}, commandList, isTopLevel);
 						stdout(formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
@@ -1190,7 +1193,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
@@ -1198,7 +1201,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: author ?? doc.author,
 							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
-						};
+						}, commandList, classified.commandPath.length < 1);
 						stderr(formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
@@ -1295,6 +1298,42 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function maybeCollapseCommandList(doc, commandList, isTopLevel) {
+	if (commandList !== "top-level" || !isTopLevel) return doc;
+	return {
+		...doc,
+		sections: doc.sections.map((section) => ({
+			...section,
+			entries: collapseTopLevelCommandEntries(section.entries)
+		}))
+	};
+}
+function collapseTopLevelCommandEntries(entries) {
+	const collapsed = [];
+	const commandIndexes = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.term.type !== "command") {
+			collapsed.push(entry);
+			continue;
+		}
+		const topLevelName = getTopLevelCommandName(entry.term.name);
+		const existingIndex = commandIndexes.get(topLevelName);
+		const isTopLevel = entry.term.name === topLevelName;
+		if (existingIndex == null) {
+			commandIndexes.set(topLevelName, collapsed.length);
+			collapsed.push(isTopLevel ? entry : { term: {
+				...entry.term,
+				name: topLevelName
+			} });
+			continue;
+		}
+		if (isTopLevel) collapsed[existingIndex] = entry;
+	}
+	return collapsed;
+}
+function getTopLevelCommandName(name) {
+	return name.split(" ", 1)[0] ?? name;
+}
 /**
 * An error class used to indicate that the command line arguments
 * could not be parsed successfully.

package/dist/index.cjs

@@ -17,6 +17,7 @@ exports.RunParserError = require_facade.RunParserError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.argument = require_primitives.argument;
 exports.bash = require_completion.bash;
+exports.biject = require_valueparser.biject;
 exports.checkBooleanOption = require_valueparser.checkBooleanOption;
 exports.checkEnumOption = require_valueparser.checkEnumOption;
 exports.choice = require_valueparser.choice;
@@ -121,6 +122,7 @@ exports.suggest = require_internal_parser.suggest;
 exports.suggestAsync = require_internal_parser.suggestAsync;
 exports.suggestSync = require_internal_parser.suggestSync;
 exports.text = require_message.text;
+exports.transform = require_valueparser.transform;
 exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;
 exports.uuid = require_valueparser.uuid;

package/dist/index.d.cts

@@ -3,13 +3,13 @@ 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, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
-import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,13 +3,13 @@ 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, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
-import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -8,8 +8,8 @@ import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/internal/mode-dispatch.cjs

@@ -37,6 +37,42 @@ function mapModeValue(mode, value, mapFn) {
 	return mapFn(value);
 }
 /**
+* Maps a value or promise while preserving the declared execution mode.
+*
+* Some internal extension hooks predate `ModeValue` and expose a plain
+* `T | Promise<T>` return type. This helper adapts those hooks back into the
+* mode-dispatch boundary before applying a mapping function.
+*
+* @param mode The execution mode.
+* @param value The value or promise to transform.
+* @param mapFn Mapping function applied to the unwrapped value.
+* @returns The mapped value with correct mode wrapping.
+* @internal
+*/
+function mapMaybePromiseByMode(mode, value, mapFn) {
+	return mapModeValue(mode, wrapForMode(mode, value), mapFn);
+}
+/**
+* Adapts an iterable or async iterable to the declared execution mode.
+*
+* @param mode The execution mode.
+* @param value The iterable to adapt.
+* @returns The iterable with correct mode wrapping.
+* @throws {TypeError} If a synchronous mode receives an async iterable.
+* @internal
+*/
+function wrapIterableForMode(mode, value) {
+	return dispatchIterableByMode(mode, () => {
+		if (Symbol.asyncIterator in value) throw new TypeError("Synchronous mode cannot wrap AsyncIterable value.");
+		return value;
+	}, () => {
+		if (Symbol.asyncIterator in value) return value;
+		return async function* () {
+			yield* value;
+		}();
+	});
+}
+/**
 * Dispatches iterable to sync or async implementation based on mode.
 *
 * @param mode The execution mode.
@@ -54,5 +90,7 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 //#endregion
 exports.dispatchByMode = dispatchByMode;
 exports.dispatchIterableByMode = dispatchIterableByMode;
+exports.mapMaybePromiseByMode = mapMaybePromiseByMode;
 exports.mapModeValue = mapModeValue;
-exports.wrapForMode = wrapForMode;
+exports.wrapForMode = wrapForMode;
+exports.wrapIterableForMode = wrapIterableForMode;

package/dist/internal/mode-dispatch.d.cts

@@ -38,14 +38,17 @@ declare function wrapForMode<M extends Mode, T>(mode: M, value: T | Promise<T>):
  */
 declare function mapModeValue<M extends Mode, T, U>(mode: M, value: ModeValue<M, T>, mapFn: (value: T) => U): ModeValue<M, U>;
 /**
- * Dispatches iterable to sync or async implementation based on mode.
+ * Maps a value or promise while preserving the declared execution mode.
+ *
+ * Some internal extension hooks predate `ModeValue` and expose a plain
+ * `T | Promise<T>` return type. This helper adapts those hooks back into the
+ * mode-dispatch boundary before applying a mapping function.
  *
  * @param mode The execution mode.
- * @param syncFn Function returning sync iterable.
- * @param asyncFn Function returning async iterable.
- * @returns The iterable with correct mode wrapping.
+ * @param value The value or promise to transform.
+ * @param mapFn Mapping function applied to the unwrapped value.
+ * @returns The mapped value with correct mode wrapping.
  * @internal
- * @since 0.10.0
  */
 //#endregion
 export { dispatchByMode, mapModeValue, wrapForMode };

package/dist/internal/mode-dispatch.d.ts

@@ -38,14 +38,17 @@ declare function wrapForMode<M extends Mode, T>(mode: M, value: T | Promise<T>):
  */
 declare function mapModeValue<M extends Mode, T, U>(mode: M, value: ModeValue<M, T>, mapFn: (value: T) => U): ModeValue<M, U>;
 /**
- * Dispatches iterable to sync or async implementation based on mode.
+ * Maps a value or promise while preserving the declared execution mode.
+ *
+ * Some internal extension hooks predate `ModeValue` and expose a plain
+ * `T | Promise<T>` return type. This helper adapts those hooks back into the
+ * mode-dispatch boundary before applying a mapping function.
  *
  * @param mode The execution mode.
- * @param syncFn Function returning sync iterable.
- * @param asyncFn Function returning async iterable.
- * @returns The iterable with correct mode wrapping.
+ * @param value The value or promise to transform.
+ * @param mapFn Mapping function applied to the unwrapped value.
+ * @returns The mapped value with correct mode wrapping.
  * @internal
- * @since 0.10.0
  */
 //#endregion
 export { dispatchByMode, mapModeValue, wrapForMode };

package/dist/internal/mode-dispatch.js

@@ -36,6 +36,42 @@ function mapModeValue(mode, value, mapFn) {
 	return mapFn(value);
 }
 /**
+* Maps a value or promise while preserving the declared execution mode.
+*
+* Some internal extension hooks predate `ModeValue` and expose a plain
+* `T | Promise<T>` return type. This helper adapts those hooks back into the
+* mode-dispatch boundary before applying a mapping function.
+*
+* @param mode The execution mode.
+* @param value The value or promise to transform.
+* @param mapFn Mapping function applied to the unwrapped value.
+* @returns The mapped value with correct mode wrapping.
+* @internal
+*/
+function mapMaybePromiseByMode(mode, value, mapFn) {
+	return mapModeValue(mode, wrapForMode(mode, value), mapFn);
+}
+/**
+* Adapts an iterable or async iterable to the declared execution mode.
+*
+* @param mode The execution mode.
+* @param value The iterable to adapt.
+* @returns The iterable with correct mode wrapping.
+* @throws {TypeError} If a synchronous mode receives an async iterable.
+* @internal
+*/
+function wrapIterableForMode(mode, value) {
+	return dispatchIterableByMode(mode, () => {
+		if (Symbol.asyncIterator in value) throw new TypeError("Synchronous mode cannot wrap AsyncIterable value.");
+		return value;
+	}, () => {
+		if (Symbol.asyncIterator in value) return value;
+		return async function* () {
+			yield* value;
+		}();
+	});
+}
+/**
 * Dispatches iterable to sync or async implementation based on mode.
 *
 * @param mode The execution mode.
@@ -51,4 +87,4 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 }
 
 //#endregion
-export { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode };
+export { dispatchByMode, dispatchIterableByMode, mapMaybePromiseByMode, mapModeValue, wrapForMode, wrapIterableForMode };