@optique/core 0.9.0-dev.202 → 0.9.0-dev.206

package/dist/facade.cjs

@@ -404,7 +404,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	return callOnCompletion(0);
 }
 function runParser(parser, programName, args, options = {}) {
-	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
+	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;
 	const helpMode = options.help?.mode ?? "option";
@@ -500,31 +500,35 @@ function runParser(parser, programName, args, options = {}) {
 					else if (commandParsers.length === 2) helpGeneratorParser = require_constructs.longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = require_constructs.longestMatch(...commandParsers);
 				}
-				const doc = require_parser.getDocPage(helpGeneratorParser, classified.commands);
-				if (doc != null) {
-					const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
-					const augmentedDoc = {
-						...doc,
-						brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
-						description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
-						footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
-					};
-					stdout(require_doc.formatDocPage(programName, augmentedDoc, {
-						colors,
-						maxWidth,
-						showDefault
-					}));
-				}
-				try {
-					return onHelp(0);
-				} catch {
-					return onHelp();
-				}
+				const displayHelp = (doc) => {
+					if (doc != null) {
+						const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
+						const augmentedDoc = {
+							...doc,
+							brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
+							description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+							footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
+						};
+						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
+							colors,
+							maxWidth,
+							showDefault
+						}));
+					}
+					try {
+						return onHelp(0);
+					} catch {
+						return onHelp();
+					}
+				};
+				const docOrPromise = require_parser.getDocPage(helpGeneratorParser, classified.commands);
+				if (docOrPromise instanceof Promise) return docOrPromise.then(displayHelp);
+				return displayHelp(docOrPromise);
 			}
 			case "error": {
-				if (aboveError === "help") {
-					const doc = require_parser.getDocPage(args.length < 1 ? augmentedParser : parser, args);
-					if (doc == null) aboveError = "usage";
+				const displayError = (doc, currentAboveError) => {
+					let effectiveAboveError = currentAboveError;
+					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
 						const augmentedDoc = {
 							...doc,
@@ -538,18 +542,25 @@ function runParser(parser, programName, args, options = {}) {
 							showDefault
 						}));
 					}
+					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+						colors,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						expandCommands: true
+					}), 7)}`);
+					const errorMessage = require_message.formatMessage(classified.error, {
+						colors,
+						quotes: !colors
+					});
+					stderr(`Error: ${errorMessage}`);
+					return onError(1);
+				};
+				if (aboveError === "help") {
+					const parserForDoc = args.length < 1 ? augmentedParser : parser;
+					const docOrPromise = require_parser.getDocPage(parserForDoc, args);
+					if (docOrPromise instanceof Promise) return docOrPromise.then((doc) => displayError(doc, aboveError));
+					return displayError(docOrPromise, aboveError);
 				}
-				if (aboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
-					colors,
-					maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
-					expandCommands: true
-				}), 7)}`);
-				const errorMessage = require_message.formatMessage(classified.error, {
-					colors,
-					quotes: !colors
-				});
-				stderr(`Error: ${errorMessage}`);
-				return onError(1);
+				return displayError(void 0, aboveError);
 			}
 			default: throw new RunParserError("Unexpected parse result type");
 		}
@@ -561,6 +572,47 @@ function runParser(parser, programName, args, options = {}) {
 	}
 }
 /**
+* Runs a synchronous command-line parser with the given options.
+*
+* This is a type-safe version of {@link runParser} that only accepts sync
+* parsers. Use this when you know your parser is sync-only to get direct
+* return values without Promise wrappers.
+*
+* @template TParser The sync parser type being executed.
+* @template THelp The return type of the onHelp callback.
+* @template TError The return type of the onError callback.
+* @param parser The synchronous command-line parser to execute.
+* @param programName The name of the program for help messages.
+* @param args The command-line arguments to parse.
+* @param options Configuration options for customizing behavior.
+* @returns The parsed result if successful.
+* @since 0.9.0
+*/
+function runParserSync(parser, programName, args, options) {
+	return runParser(parser, programName, args, options);
+}
+/**
+* Runs any command-line parser asynchronously with the given options.
+*
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with parsers that may contain
+* async value parsers.
+*
+* @template TParser The parser type being executed.
+* @template THelp The return type of the onHelp callback.
+* @template TError The return type of the onError callback.
+* @param parser The command-line parser to execute.
+* @param programName The name of the program for help messages.
+* @param args The command-line arguments to parse.
+* @param options Configuration options for customizing behavior.
+* @returns A Promise of the parsed result if successful.
+* @since 0.9.0
+*/
+function runParserAsync(parser, programName, args, options) {
+	const result = runParser(parser, programName, args, options);
+	return Promise.resolve(result);
+}
+/**
 * @deprecated Use `runParser()` instead. This export will be removed in
 *             a future major version. The name `run` conflicts with
 *             `@optique/run`'s `run()` function, causing IDE autocomplete
@@ -590,4 +642,6 @@ function indentLines(text$1, indent) {
 exports.RunError = RunError;
 exports.RunParserError = RunParserError;
 exports.run = run;
-exports.runParser = runParser;
+exports.runParser = runParser;
+exports.runParserAsync = runParserAsync;
+exports.runParserSync = runParserSync;

package/dist/facade.d.cts

@@ -217,6 +217,42 @@ interface RunOptions<THelp, TError> {
 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>>;
+/**
+ * Runs a synchronous command-line parser with the given options.
+ *
+ * This is a type-safe version of {@link runParser} that only accepts sync
+ * parsers. Use this when you know your parser is sync-only to get direct
+ * return values without Promise wrappers.
+ *
+ * @template TParser The sync parser type being executed.
+ * @template THelp The return type of the onHelp callback.
+ * @template TError The return type of the onError callback.
+ * @param parser The synchronous command-line parser to execute.
+ * @param programName The name of the program for help messages.
+ * @param args The command-line arguments to parse.
+ * @param options Configuration options for customizing behavior.
+ * @returns The parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * Runs any command-line parser asynchronously with the given options.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with parsers that may contain
+ * async value parsers.
+ *
+ * @template TParser The parser type being executed.
+ * @template THelp The return type of the onHelp callback.
+ * @template TError The return type of the onError callback.
+ * @param parser The command-line parser to execute.
+ * @param programName The name of the program for help messages.
+ * @param args The command-line arguments to parse.
+ * @param options Configuration options for customizing behavior.
+ * @returns A Promise of the parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 /**
  * @deprecated Use `runParser()` instead. This export will be removed in
  *             a future major version. The name `run` conflicts with
@@ -237,4 +273,4 @@ declare class RunParserError extends Error {
  */
 declare const RunError: typeof RunParserError;
 //#endregion
-export { RunError, RunOptions, RunParserError, run, runParser };
+export { RunError, RunOptions, RunParserError, run, runParser, runParserAsync, runParserSync };

package/dist/facade.d.ts

@@ -217,6 +217,42 @@ interface RunOptions<THelp, TError> {
 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>>;
+/**
+ * Runs a synchronous command-line parser with the given options.
+ *
+ * This is a type-safe version of {@link runParser} that only accepts sync
+ * parsers. Use this when you know your parser is sync-only to get direct
+ * return values without Promise wrappers.
+ *
+ * @template TParser The sync parser type being executed.
+ * @template THelp The return type of the onHelp callback.
+ * @template TError The return type of the onError callback.
+ * @param parser The synchronous command-line parser to execute.
+ * @param programName The name of the program for help messages.
+ * @param args The command-line arguments to parse.
+ * @param options Configuration options for customizing behavior.
+ * @returns The parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * Runs any command-line parser asynchronously with the given options.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with parsers that may contain
+ * async value parsers.
+ *
+ * @template TParser The parser type being executed.
+ * @template THelp The return type of the onHelp callback.
+ * @template TError The return type of the onError callback.
+ * @param parser The command-line parser to execute.
+ * @param programName The name of the program for help messages.
+ * @param args The command-line arguments to parse.
+ * @param options Configuration options for customizing behavior.
+ * @returns A Promise of the parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 /**
  * @deprecated Use `runParser()` instead. This export will be removed in
  *             a future major version. The name `run` conflicts with
@@ -237,4 +273,4 @@ declare class RunParserError extends Error {
  */
 declare const RunError: typeof RunParserError;
 //#endregion
-export { RunError, RunOptions, RunParserError, run, runParser };
+export { RunError, RunOptions, RunParserError, run, runParser, runParserAsync, runParserSync };

package/dist/facade.js

@@ -404,7 +404,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	return callOnCompletion(0);
 }
 function runParser(parser, programName, args, options = {}) {
-	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
+	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;
 	const helpMode = options.help?.mode ?? "option";
@@ -500,31 +500,35 @@ function runParser(parser, programName, args, options = {}) {
 					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = longestMatch(...commandParsers);
 				}
-				const doc = getDocPage(helpGeneratorParser, classified.commands);
-				if (doc != null) {
-					const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
-					const augmentedDoc = {
-						...doc,
-						brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
-						description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
-						footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
-					};
-					stdout(formatDocPage(programName, augmentedDoc, {
-						colors,
-						maxWidth,
-						showDefault
-					}));
-				}
-				try {
-					return onHelp(0);
-				} catch {
-					return onHelp();
-				}
+				const displayHelp = (doc) => {
+					if (doc != null) {
+						const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
+						const augmentedDoc = {
+							...doc,
+							brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
+							description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+							footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
+						};
+						stdout(formatDocPage(programName, augmentedDoc, {
+							colors,
+							maxWidth,
+							showDefault
+						}));
+					}
+					try {
+						return onHelp(0);
+					} catch {
+						return onHelp();
+					}
+				};
+				const docOrPromise = getDocPage(helpGeneratorParser, classified.commands);
+				if (docOrPromise instanceof Promise) return docOrPromise.then(displayHelp);
+				return displayHelp(docOrPromise);
 			}
 			case "error": {
-				if (aboveError === "help") {
-					const doc = getDocPage(args.length < 1 ? augmentedParser : parser, args);
-					if (doc == null) aboveError = "usage";
+				const displayError = (doc, currentAboveError) => {
+					let effectiveAboveError = currentAboveError;
+					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
 						const augmentedDoc = {
 							...doc,
@@ -538,18 +542,25 @@ function runParser(parser, programName, args, options = {}) {
 							showDefault
 						}));
 					}
+					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
+						colors,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						expandCommands: true
+					}), 7)}`);
+					const errorMessage = formatMessage(classified.error, {
+						colors,
+						quotes: !colors
+					});
+					stderr(`Error: ${errorMessage}`);
+					return onError(1);
+				};
+				if (aboveError === "help") {
+					const parserForDoc = args.length < 1 ? augmentedParser : parser;
+					const docOrPromise = getDocPage(parserForDoc, args);
+					if (docOrPromise instanceof Promise) return docOrPromise.then((doc) => displayError(doc, aboveError));
+					return displayError(docOrPromise, aboveError);
 				}
-				if (aboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
-					colors,
-					maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
-					expandCommands: true
-				}), 7)}`);
-				const errorMessage = formatMessage(classified.error, {
-					colors,
-					quotes: !colors
-				});
-				stderr(`Error: ${errorMessage}`);
-				return onError(1);
+				return displayError(void 0, aboveError);
 			}
 			default: throw new RunParserError("Unexpected parse result type");
 		}
@@ -561,6 +572,47 @@ function runParser(parser, programName, args, options = {}) {
 	}
 }
 /**
+* Runs a synchronous command-line parser with the given options.
+*
+* This is a type-safe version of {@link runParser} that only accepts sync
+* parsers. Use this when you know your parser is sync-only to get direct
+* return values without Promise wrappers.
+*
+* @template TParser The sync parser type being executed.
+* @template THelp The return type of the onHelp callback.
+* @template TError The return type of the onError callback.
+* @param parser The synchronous command-line parser to execute.
+* @param programName The name of the program for help messages.
+* @param args The command-line arguments to parse.
+* @param options Configuration options for customizing behavior.
+* @returns The parsed result if successful.
+* @since 0.9.0
+*/
+function runParserSync(parser, programName, args, options) {
+	return runParser(parser, programName, args, options);
+}
+/**
+* Runs any command-line parser asynchronously with the given options.
+*
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with parsers that may contain
+* async value parsers.
+*
+* @template TParser The parser type being executed.
+* @template THelp The return type of the onHelp callback.
+* @template TError The return type of the onError callback.
+* @param parser The command-line parser to execute.
+* @param programName The name of the program for help messages.
+* @param args The command-line arguments to parse.
+* @param options Configuration options for customizing behavior.
+* @returns A Promise of the parsed result if successful.
+* @since 0.9.0
+*/
+function runParserAsync(parser, programName, args, options) {
+	const result = runParser(parser, programName, args, options);
+	return Promise.resolve(result);
+}
+/**
 * @deprecated Use `runParser()` instead. This export will be removed in
 *             a future major version. The name `run` conflicts with
 *             `@optique/run`'s `run()` function, causing IDE autocomplete
@@ -587,4 +639,4 @@ function indentLines(text$1, indent) {
 }
 
 //#endregion
-export { RunError, RunParserError, run, runParser };
+export { RunError, RunParserError, run, runParser, runParserAsync, runParserSync };

package/dist/index.cjs

@@ -35,6 +35,8 @@ exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
 exports.getDocPage = require_parser.getDocPage;
+exports.getDocPageAsync = require_parser.getDocPageAsync;
+exports.getDocPageSync = require_parser.getDocPageSync;
 exports.group = require_constructs.group;
 exports.integer = require_valueparser.integer;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
@@ -61,6 +63,8 @@ exports.passThrough = require_primitives.passThrough;
 exports.pwsh = require_completion.pwsh;
 exports.run = require_facade.run;
 exports.runParser = require_facade.runParser;
+exports.runParserAsync = require_facade.runParserAsync;
+exports.runParserSync = require_facade.runParserSync;
 exports.string = require_valueparser.string;
 exports.suggest = require_parser.suggest;
 exports.suggestAsync = require_parser.suggestAsync;

package/dist/index.d.cts

@@ -5,8 +5,8 @@ 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, 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, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.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 { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
-import { RunError, RunOptions, RunParserError, run, runParser } from "./facade.cjs";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, 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, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, pwsh, run, runParser, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, values, withDefault, zsh };
+import { RunError, RunOptions, RunParserError, run, runParser, runParserAsync, runParserSync } from "./facade.cjs";
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, 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, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, pwsh, run, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -5,8 +5,8 @@ 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, 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, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.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 { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { RunError, RunOptions, RunParserError, run, runParser } from "./facade.js";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, 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, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, pwsh, run, runParser, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, values, withDefault, zsh };
+import { RunError, RunOptions, RunParserError, run, runParser, runParserAsync, runParserSync } from "./facade.js";
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, 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, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, pwsh, run, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -7,7 +7,7 @@ import { WithDefaultError, map, multiple, optional, withDefault } from "./modifi
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
-import { getDocPage, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
-import { RunError, RunParserError, run, runParser } from "./facade.js";
+import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
+import { RunError, RunParserError, run, runParser, runParserAsync, runParserSync } from "./facade.js";
 
-export { DuplicateOptionError, RunError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, pwsh, run, runParser, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { DuplicateOptionError, RunError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, pwsh, run, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/parser.cjs

@@ -264,39 +264,44 @@ function findCommandInExclusive(term, commandName) {
 	return null;
 }
 /**
-* Generates a documentation page for a parser based on its current state after
-* attempting to parse the provided arguments. This function is useful for
-* creating help documentation that reflects the current parsing context.
+* Generates a documentation page for a synchronous parser.
 *
-* The function works by:
-* 1. Attempting to parse the provided arguments to determine the current state
-* 2. Generating documentation fragments from the parser's current state
-* 3. Organizing fragments into entries and sections
-* 4. Resolving command usage terms based on parsed arguments
+* This is the sync-specific version of {@link getDocPage}. It only accepts
+* sync parsers and returns the documentation page directly (not wrapped
+* in a Promise).
 *
-* @param parser The parser to generate documentation for
-* @param args Optional array of command-line arguments that have been parsed
-*             so far. Defaults to an empty array. This is used to determine
-*             the current parsing context and generate contextual documentation.
-* @returns A {@link DocPage} containing usage information, sections, and
-*          optional description, or `undefined` if no documentation can be
-*          generated.
-*
-* @example
-* ```typescript
-* const parser = object({
-*   verbose: option("-v", "--verbose"),
-*   port: option("-p", "--port", integer())
-* });
+* @param parser The sync parser to generate documentation for.
+* @param args Optional array of command-line arguments for context.
+* @returns A {@link DocPage} or `undefined`.
+* @since 0.9.0
+*/
+function getDocPageSync(parser, args = []) {
+	return getDocPageSyncImpl(parser, args);
+}
+/**
+* Generates a documentation page for any parser, returning a Promise.
 *
-* // Get documentation for the root parser
-* const rootDoc = getDocPage(parser);
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with parsers that may contain
+* async value parsers.
 *
-* // Get documentation after parsing some arguments
-* const contextDoc = getDocPage(parser, ["-v"]);
-* ```
+* @param parser The parser to generate documentation for.
+* @param args Optional array of command-line arguments for context.
+* @returns A Promise of {@link DocPage} or `undefined`.
+* @since 0.9.0
 */
+function getDocPageAsync(parser, args = []) {
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args));
+	return getDocPageAsyncImpl(parser, args);
+}
 function getDocPage(parser, args = []) {
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args);
+	return getDocPageAsyncImpl(parser, args);
+}
+/**
+* Internal sync implementation of getDocPage.
+*/
+function getDocPageSyncImpl(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -308,6 +313,30 @@ function getDocPage(parser, args = []) {
 		if (!result.success) break;
 		context = result.next;
 	} while (context.buffer.length > 0);
+	return buildDocPage(parser, context, args);
+}
+/**
+* Internal async implementation of getDocPage.
+*/
+async function getDocPageAsyncImpl(parser, args) {
+	let context = {
+		buffer: args,
+		optionsTerminated: false,
+		state: parser.initialState,
+		usage: parser.usage
+	};
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) break;
+		context = result.next;
+	} while (context.buffer.length > 0);
+	return buildDocPage(parser, context, args);
+}
+/**
+* Builds a DocPage from the parser and context.
+* Shared by both sync and async implementations.
+*/
+function buildDocPage(parser, context, args) {
 	const { description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
@@ -351,6 +380,8 @@ exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
 exports.flag = require_primitives.flag;
 exports.getDocPage = getDocPage;
+exports.getDocPageAsync = getDocPageAsync;
+exports.getDocPageSync = getDocPageSync;
 exports.group = require_constructs.group;
 exports.longestMatch = require_constructs.longestMatch;
 exports.map = require_modifiers.map;

package/dist/parser.d.cts

@@ -440,6 +440,32 @@ declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonl
  * @since 0.6.0
  */
 declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly [string, ...readonly string[]]): ModeValue<M, readonly Suggestion[]>;
+/**
+ * Generates a documentation page for a synchronous parser.
+ *
+ * This is the sync-specific version of {@link getDocPage}. It only accepts
+ * sync parsers and returns the documentation page directly (not wrapped
+ * in a Promise).
+ *
+ * @param parser The sync parser to generate documentation for.
+ * @param args Optional array of command-line arguments for context.
+ * @returns A {@link DocPage} or `undefined`.
+ * @since 0.9.0
+ */
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+/**
+ * Generates a documentation page for any parser, returning a Promise.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with parsers that may contain
+ * async value parsers.
+ *
+ * @param parser The parser to generate documentation for.
+ * @param args Optional array of command-line arguments for context.
+ * @returns A Promise of {@link DocPage} or `undefined`.
+ * @since 0.9.0
+ */
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -451,13 +477,16 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  * 3. Organizing fragments into entries and sections
  * 4. Resolving command usage terms based on parsed arguments
  *
+ * For sync parsers, returns the documentation page directly.
+ * For async parsers, returns a Promise of the documentation page.
+ *
  * @param parser The parser to generate documentation for
  * @param args Optional array of command-line arguments that have been parsed
  *             so far. Defaults to an empty array. This is used to determine
  *             the current parsing context and generate contextual documentation.
- * @returns A {@link DocPage} containing usage information, sections, and
- *          optional description, or `undefined` if no documentation can be
- *          generated.
+ * @returns For sync parsers, returns a {@link DocPage} directly.
+ *          For async parsers, returns a Promise of {@link DocPage}.
+ *          Returns `undefined` if no documentation can be generated.
  *
  * @example
  * ```typescript
@@ -466,13 +495,16 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  *   port: option("-p", "--port", integer())
  * });
  *
- * // Get documentation for the root parser
+ * // Get documentation for sync parser
  * const rootDoc = getDocPage(parser);
  *
- * // Get documentation after parsing some arguments
- * const contextDoc = getDocPage(parser, ["-v"]);
+ * // Get documentation for async parser
+ * const asyncDoc = await getDocPage(asyncParser);
  * ```
+ * @since 0.9.0 Updated to support async parsers.
  */
 declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[]): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.d.ts

@@ -440,6 +440,32 @@ declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonl
  * @since 0.6.0
  */
 declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly [string, ...readonly string[]]): ModeValue<M, readonly Suggestion[]>;
+/**
+ * Generates a documentation page for a synchronous parser.
+ *
+ * This is the sync-specific version of {@link getDocPage}. It only accepts
+ * sync parsers and returns the documentation page directly (not wrapped
+ * in a Promise).
+ *
+ * @param parser The sync parser to generate documentation for.
+ * @param args Optional array of command-line arguments for context.
+ * @returns A {@link DocPage} or `undefined`.
+ * @since 0.9.0
+ */
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+/**
+ * Generates a documentation page for any parser, returning a Promise.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with parsers that may contain
+ * async value parsers.
+ *
+ * @param parser The parser to generate documentation for.
+ * @param args Optional array of command-line arguments for context.
+ * @returns A Promise of {@link DocPage} or `undefined`.
+ * @since 0.9.0
+ */
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -451,13 +477,16 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  * 3. Organizing fragments into entries and sections
  * 4. Resolving command usage terms based on parsed arguments
  *
+ * For sync parsers, returns the documentation page directly.
+ * For async parsers, returns a Promise of the documentation page.
+ *
  * @param parser The parser to generate documentation for
  * @param args Optional array of command-line arguments that have been parsed
  *             so far. Defaults to an empty array. This is used to determine
  *             the current parsing context and generate contextual documentation.
- * @returns A {@link DocPage} containing usage information, sections, and
- *          optional description, or `undefined` if no documentation can be
- *          generated.
+ * @returns For sync parsers, returns a {@link DocPage} directly.
+ *          For async parsers, returns a Promise of {@link DocPage}.
+ *          Returns `undefined` if no documentation can be generated.
  *
  * @example
  * ```typescript
@@ -466,13 +495,16 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  *   port: option("-p", "--port", integer())
  * });
  *
- * // Get documentation for the root parser
+ * // Get documentation for sync parser
  * const rootDoc = getDocPage(parser);
  *
- * // Get documentation after parsing some arguments
- * const contextDoc = getDocPage(parser, ["-v"]);
+ * // Get documentation for async parser
+ * const asyncDoc = await getDocPage(asyncParser);
  * ```
+ * @since 0.9.0 Updated to support async parsers.
  */
 declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[]): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.js

@@ -264,39 +264,44 @@ function findCommandInExclusive(term, commandName) {
 	return null;
 }
 /**
-* Generates a documentation page for a parser based on its current state after
-* attempting to parse the provided arguments. This function is useful for
-* creating help documentation that reflects the current parsing context.
+* Generates a documentation page for a synchronous parser.
 *
-* The function works by:
-* 1. Attempting to parse the provided arguments to determine the current state
-* 2. Generating documentation fragments from the parser's current state
-* 3. Organizing fragments into entries and sections
-* 4. Resolving command usage terms based on parsed arguments
+* This is the sync-specific version of {@link getDocPage}. It only accepts
+* sync parsers and returns the documentation page directly (not wrapped
+* in a Promise).
 *
-* @param parser The parser to generate documentation for
-* @param args Optional array of command-line arguments that have been parsed
-*             so far. Defaults to an empty array. This is used to determine
-*             the current parsing context and generate contextual documentation.
-* @returns A {@link DocPage} containing usage information, sections, and
-*          optional description, or `undefined` if no documentation can be
-*          generated.
-*
-* @example
-* ```typescript
-* const parser = object({
-*   verbose: option("-v", "--verbose"),
-*   port: option("-p", "--port", integer())
-* });
+* @param parser The sync parser to generate documentation for.
+* @param args Optional array of command-line arguments for context.
+* @returns A {@link DocPage} or `undefined`.
+* @since 0.9.0
+*/
+function getDocPageSync(parser, args = []) {
+	return getDocPageSyncImpl(parser, args);
+}
+/**
+* Generates a documentation page for any parser, returning a Promise.
 *
-* // Get documentation for the root parser
-* const rootDoc = getDocPage(parser);
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with parsers that may contain
+* async value parsers.
 *
-* // Get documentation after parsing some arguments
-* const contextDoc = getDocPage(parser, ["-v"]);
-* ```
+* @param parser The parser to generate documentation for.
+* @param args Optional array of command-line arguments for context.
+* @returns A Promise of {@link DocPage} or `undefined`.
+* @since 0.9.0
 */
+function getDocPageAsync(parser, args = []) {
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args));
+	return getDocPageAsyncImpl(parser, args);
+}
 function getDocPage(parser, args = []) {
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args);
+	return getDocPageAsyncImpl(parser, args);
+}
+/**
+* Internal sync implementation of getDocPage.
+*/
+function getDocPageSyncImpl(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -308,6 +313,30 @@ function getDocPage(parser, args = []) {
 		if (!result.success) break;
 		context = result.next;
 	} while (context.buffer.length > 0);
+	return buildDocPage(parser, context, args);
+}
+/**
+* Internal async implementation of getDocPage.
+*/
+async function getDocPageAsyncImpl(parser, args) {
+	let context = {
+		buffer: args,
+		optionsTerminated: false,
+		state: parser.initialState,
+		usage: parser.usage
+	};
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) break;
+		context = result.next;
+	} while (context.buffer.length > 0);
+	return buildDocPage(parser, context, args);
+}
+/**
+* Builds a DocPage from the parser and context.
+* Shared by both sync and async implementations.
+*/
+function buildDocPage(parser, context, args) {
 	const { description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
@@ -342,4 +371,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.9.0-dev.202+8c415cd6",
+  "version": "0.9.0-dev.206+78abd1b3",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",