@optique/core 0.10.0-dev.323 → 0.10.0-dev.327

package/dist/dependency.js

@@ -531,6 +531,35 @@ function isDeferredParseState(value) {
 	return typeof value === "object" && value !== null && deferredParseMarker in value && value[deferredParseMarker] === true;
 }
 /**
+* Gets all dependency IDs from a derived parser.
+* If the parser was created with `deriveFrom` (multiple dependencies),
+* returns the array of dependency IDs. Otherwise, returns an array
+* containing the single dependency ID.
+*
+* @param parser The derived value parser to get dependency IDs from.
+* @returns An array of dependency ID symbols.
+* @internal
+* @since 0.10.0
+*/
+function getDependencyIds(parser) {
+	if (dependencyIds in parser) return parser[dependencyIds];
+	return [parser[dependencyId]];
+}
+/**
+* Gets the default values function from a derived parser, if present.
+* This function is available on parsers created with `deriveFrom` that
+* specify default values for their dependencies.
+*
+* @param parser The derived value parser to get the default values function from.
+* @returns The default values function, or undefined if not available.
+* @internal
+* @since 0.10.0
+*/
+function getDefaultValuesFunction(parser) {
+	if (defaultValues in parser) return parser[defaultValues];
+	return void 0;
+}
+/**
 * Creates a deferred parse state for a DerivedValueParser.
 *
 * @template T The type of value the parser will produce.
@@ -719,4 +748,4 @@ function formatDependencyError(error) {
 }
 
 //#endregion
-export { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };
+export { DependencyRegistry, 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 };

package/dist/facade.cjs

@@ -403,7 +403,30 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 	return callOnCompletion(0);
 }
-function runParser(parser, programName, args, options = {}) {
+function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
+	const isProgram = typeof programNameOrArgs !== "string";
+	let parser;
+	let programName;
+	let args;
+	let options;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programName = program.metadata.name;
+		args = programNameOrArgs;
+		options = argsOrOptions ?? {};
+		options = {
+			...options,
+			brief: options.brief ?? program.metadata.brief,
+			description: options.description ?? program.metadata.description,
+			footer: options.footer ?? program.metadata.footer
+		};
+	} else {
+		parser = parserOrProgram;
+		programName = programNameOrArgs;
+		args = argsOrOptions;
+		options = optionsParam ?? {};
+	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;

package/dist/facade.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
+import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
 
@@ -213,7 +214,10 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
+ * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
+declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
 declare function runParser<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
 declare function runParser<TParser extends Parser<"async", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): ModeValue<InferMode<TParser>, InferValue<TParser>>;

package/dist/facade.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
+import { Program } from "./program.js";
 
 //#region src/facade.d.ts
 
@@ -213,7 +214,10 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
+ * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
+declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
 declare function runParser<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
 declare function runParser<TParser extends Parser<"async", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): ModeValue<InferMode<TParser>, InferValue<TParser>>;

package/dist/facade.js

@@ -403,7 +403,30 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 	return callOnCompletion(0);
 }
-function runParser(parser, programName, args, options = {}) {
+function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
+	const isProgram = typeof programNameOrArgs !== "string";
+	let parser;
+	let programName;
+	let args;
+	let options;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programName = program.metadata.name;
+		args = programNameOrArgs;
+		options = argsOrOptions ?? {};
+		options = {
+			...options,
+			brief: options.brief ?? program.metadata.brief,
+			description: options.description ?? program.metadata.description,
+			footer: options.footer ?? program.metadata.footer
+		};
+	} else {
+		parser = parserOrProgram;
+		programName = programNameOrArgs;
+		args = argsOrOptions;
+		options = optionsParam ?? {};
+	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;

package/dist/index.cjs

@@ -50,6 +50,8 @@ exports.formatDocPage = require_doc.formatDocPage;
 exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
+exports.getDefaultValuesFunction = require_dependency.getDefaultValuesFunction;
+exports.getDependencyIds = require_dependency.getDependencyIds;
 exports.getDocPage = require_parser.getDocPage;
 exports.getDocPageAsync = require_parser.getDocPageAsync;
 exports.getDocPageSync = require_parser.getDocPageSync;

package/dist/index.d.cts

@@ -5,9 +5,9 @@ import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, Doc
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, 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, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.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";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.cjs";
-export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -5,9 +5,9 @@ import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, Doc
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, 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, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.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";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
-export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
+import { DependencyRegistry, 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";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
@@ -11,4 +11,4 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/mode-dispatch.cjs

@@ -0,0 +1,38 @@
+
+//#region src/mode-dispatch.ts
+/**
+* Dispatches to sync or async implementation based on mode.
+*
+* This function encapsulates the necessary type assertions when branching
+* on runtime mode values. TypeScript cannot narrow `ModeValue<M, T>` based
+* on `mode === "async"` checks, so we must use type assertions.
+*
+* @param mode The execution mode.
+* @param syncFn Function to call for sync execution.
+* @param asyncFn Function to call for async execution.
+* @returns The result with correct mode wrapping.
+* @internal
+* @since 0.10.0
+*/
+function dispatchByMode(mode, syncFn, asyncFn) {
+	if (mode === "async") return asyncFn();
+	return syncFn();
+}
+/**
+* Dispatches iterable to sync or async implementation based on mode.
+*
+* @param mode The execution mode.
+* @param syncFn Function returning sync iterable.
+* @param asyncFn Function returning async iterable.
+* @returns The iterable with correct mode wrapping.
+* @internal
+* @since 0.10.0
+*/
+function dispatchIterableByMode(mode, syncFn, asyncFn) {
+	if (mode === "async") return asyncFn();
+	return syncFn();
+}
+
+//#endregion
+exports.dispatchByMode = dispatchByMode;
+exports.dispatchIterableByMode = dispatchIterableByMode;

package/dist/mode-dispatch.js

@@ -0,0 +1,36 @@
+//#region src/mode-dispatch.ts
+/**
+* Dispatches to sync or async implementation based on mode.
+*
+* This function encapsulates the necessary type assertions when branching
+* on runtime mode values. TypeScript cannot narrow `ModeValue<M, T>` based
+* on `mode === "async"` checks, so we must use type assertions.
+*
+* @param mode The execution mode.
+* @param syncFn Function to call for sync execution.
+* @param asyncFn Function to call for async execution.
+* @returns The result with correct mode wrapping.
+* @internal
+* @since 0.10.0
+*/
+function dispatchByMode(mode, syncFn, asyncFn) {
+	if (mode === "async") return asyncFn();
+	return syncFn();
+}
+/**
+* Dispatches iterable to sync or async implementation based on mode.
+*
+* @param mode The execution mode.
+* @param syncFn Function returning sync iterable.
+* @param asyncFn Function returning async iterable.
+* @returns The iterable with correct mode wrapping.
+* @internal
+* @since 0.10.0
+*/
+function dispatchIterableByMode(mode, syncFn, asyncFn) {
+	if (mode === "async") return asyncFn();
+	return syncFn();
+}
+
+//#endregion
+export { dispatchByMode, dispatchIterableByMode };

package/dist/modifiers.cjs

@@ -1,5 +1,6 @@
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
+const require_mode_dispatch = require('./mode-dispatch.cjs');
 
 //#region src/modifiers.ts
 /**
@@ -74,7 +75,6 @@ function processOptionalStyleResult(result, innerState, context) {
 */
 function optional(parser) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	function* suggestSync(context, prefix) {
 		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
 		yield* syncParser.suggest({
@@ -107,36 +107,27 @@ function optional(parser) {
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		parse(context) {
-			if (isAsync) return parseOptionalStyleAsync(context, parser);
-			return parseOptionalStyleSync(context, syncParser);
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
 			if (typeof state === "undefined") {
-				if (innerHasWrappedDependency && wrappedPendingState) {
-					if (!isAsync) return syncParser.complete([wrappedPendingState]);
-					return parser.complete([wrappedPendingState]);
-				}
+				if (innerHasWrappedDependency && wrappedPendingState) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
 				return {
 					success: true,
 					value: void 0
 				};
 			}
 			if (Array.isArray(state) && state.length === 1 && require_dependency.isPendingDependencySourceState(state[0])) {
-				if (innerHasWrappedDependency) {
-					if (!isAsync) return syncParser.complete(state);
-					return parser.complete(state);
-				}
+				if (innerHasWrappedDependency) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 				return {
 					success: true,
 					value: void 0
 				};
 			}
-			if (!isAsync) return syncParser.complete(state[0]);
-			return parser.complete(state[0]);
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state[0]), () => parser.complete(state[0]));
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -183,7 +174,6 @@ var WithDefaultError = class extends Error {
 };
 function withDefault(parser, defaultValue, options) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	function* suggestSync(context, prefix) {
 		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
 		yield* syncParser.suggest({
@@ -213,13 +203,12 @@ function withDefault(parser, defaultValue, options) {
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		parse(context) {
-			if (isAsync) return parseOptionalStyleAsync(context, parser);
-			return parseOptionalStyleSync(context, syncParser);
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
 			if (typeof state === "undefined") {
 				if (require_dependency.transformsDependencyValue(parser)) {
-					const innerResult = !isAsync ? syncParser.complete(void 0) : parser.complete(void 0);
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
 							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -277,7 +266,7 @@ function withDefault(parser, defaultValue, options) {
 			}
 			if (require_dependency.isPendingDependencySourceState(state[0])) {
 				if (require_dependency.transformsDependencyValue(parser)) {
-					const innerResult = !isAsync ? syncParser.complete(state) : parser.complete(state);
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
 							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -320,12 +309,10 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			if (!isAsync) return syncParser.complete(state[0]);
-			return parser.complete(state[0]);
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state[0]), () => parser.complete(state[0]));
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -432,7 +419,6 @@ function map(parser, transform) {
 */
 function multiple(parser, options = {}) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	const { min = 0, max = Infinity } = options;
 	const parseSync = (context) => {
 		let added = context.state.length < 1;
@@ -494,11 +480,10 @@ function multiple(parser, options = {}) {
 		}],
 		initialState: [],
 		parse(context) {
-			if (isAsync) return parseAsync(context);
-			return parseSync(context);
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state) {
-			if (!isAsync) {
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
 				const result = [];
 				for (const s of state) {
 					const valueResult = syncParser.complete(s);
@@ -509,8 +494,7 @@ function multiple(parser, options = {}) {
 					};
 				}
 				return validateMultipleResult(result);
-			}
-			return (async () => {
+			}, async () => {
 				const results = await Promise.all(state.map((s) => parser.complete(s)));
 				const values = [];
 				for (const valueResult of results) if (valueResult.success) values.push(valueResult.value);
@@ -519,7 +503,7 @@ function multiple(parser, options = {}) {
 					error: valueResult.error
 				};
 				return validateMultipleResult(values);
-			})();
+			});
 		},
 		suggest(context, prefix) {
 			const innerState = context.state.length > 0 ? context.state.at(-1) : parser.initialState;
@@ -535,19 +519,18 @@ function multiple(parser, options = {}) {
 				if (suggestion.kind === "literal") return !selectedValues.has(suggestion.text);
 				return true;
 			};
-			if (isAsync) return async function* () {
+			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, function* () {
+				for (const s of syncParser.suggest({
+					...context,
+					state: innerState
+				}, prefix)) if (shouldInclude(s)) yield s;
+			}, async function* () {
 				const suggestions = parser.suggest({
 					...context,
 					state: innerState
 				}, prefix);
 				for await (const s of suggestions) if (shouldInclude(s)) yield s;
-			}();
-			return function* () {
-				for (const s of syncParser.suggest({
-					...context,
-					state: innerState
-				}, prefix)) if (shouldInclude(s)) yield s;
-			}();
+			});
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
@@ -617,7 +600,6 @@ function multiple(parser, options = {}) {
 */
 function nonEmpty(parser) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -643,8 +625,7 @@ function nonEmpty(parser) {
 		usage: parser.usage,
 		initialState: parser.initialState,
 		parse(context) {
-			if (isAsync) return parseAsync(context);
-			return parseSync(context);
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state) {
 			return parser.complete(state);