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

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;

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 };
+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, 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 };
+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, 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 { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunError, RunParserError, run, runParser } 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, 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.204+0747d0e6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",