@optique/core 0.9.0-dev.217 → 0.9.0-dev.224

package/dist/parser.cjs

@@ -9,23 +9,17 @@ const require_primitives = require('./primitives.cjs');
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
 * argument until all arguments are consumed or an error occurs.
-*
-* This function only accepts synchronous parsers. For asynchronous parsers,
-* use {@link parseAsync}.
-*
 * @template T The type of the value produced by the parser.
 * @param parser The combined {@link Parser} to use for parsing the input
-*               arguments.  Must be a synchronous parser.
+*               arguments.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
 * @returns A {@link Result} object indicating whether the parsing was
 *          successful or not.  If successful, it contains the parsed value of
 *          type `T`.  If not, it contains an error message describing the
 *          failure.
-* @since 0.9.0 Renamed from the original `parse` function which now delegates
-*              to this for sync parsers.
 */
-function parseSync(parser, args) {
+function parse(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -55,86 +49,11 @@ function parseSync(parser, args) {
 	};
 }
 /**
-* Parses an array of command-line arguments using the provided combined parser.
-* This function processes the input arguments, applying the parser to each
-* argument until all arguments are consumed or an error occurs.
-*
-* This function accepts any parser (sync or async) and always returns a Promise.
-* For synchronous parsing with sync parsers, use {@link parseSync} instead.
-*
-* @template T The type of the value produced by the parser.
-* @param parser The combined {@link Parser} to use for parsing the input
-*               arguments.
-* @param args The array of command-line arguments to parse.  Usually this is
-*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
-* @returns A Promise that resolves to a {@link Result} object indicating
-*          whether the parsing was successful or not.
-* @since 0.9.0
-*/
-async function parseAsync(parser, args) {
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: parser.initialState,
-		usage: parser.usage
-	};
-	do {
-		const result = await parser.parse(context);
-		if (!result.success) return {
-			success: false,
-			error: result.error
-		};
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
-			success: false,
-			error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
-		};
-	} while (context.buffer.length > 0);
-	const endResult = await parser.complete(context.state);
-	return endResult.success ? {
-		success: true,
-		value: endResult.value
-	} : {
-		success: false,
-		error: endResult.error
-	};
-}
-/**
-* Parses an array of command-line arguments using the provided combined parser.
-* This function processes the input arguments, applying the parser to each
-* argument until all arguments are consumed or an error occurs.
-*
-* The return type depends on the parser's mode:
-* - Sync parsers return `Result<T>` directly.
-* - Async parsers return `Promise<Result<T>>`.
-*
-* For explicit control, use {@link parseSync} or {@link parseAsync}.
-*
-* @template M The execution mode of the parser.
-* @template T The type of the value produced by the parser.
-* @param parser The combined {@link Parser} to use for parsing the input
-*               arguments.
-* @param args The array of command-line arguments to parse.  Usually this is
-*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
-* @returns A {@link Result} object (for sync) or Promise thereof (for async)
-*          indicating whether the parsing was successful or not.
-*/
-function parse(parser, args) {
-	if (parser.$mode === "async") return parseAsync(parser, args);
-	return parseSync(parser, args);
-}
-/**
 * Generates command-line suggestions based on current parsing state.
 * This function processes the input arguments up to the last argument,
 * then calls the parser's suggest method with the remaining prefix.
-*
-* This function only accepts synchronous parsers. For asynchronous parsers,
-* use {@link suggestAsync}.
-*
 * @template T The type of the value produced by the parser.
 * @param parser The {@link Parser} to use for generating suggestions.
-*               Must be a synchronous parser.
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
@@ -148,17 +67,16 @@ function parse(parser, args) {
 * });
 *
 * // Get suggestions for options starting with "--"
-* const suggestions = suggestSync(parser, ["--"]);
+* const suggestions = suggest(parser, ["--"]);
 * // Returns: [{ text: "--verbose" }, { text: "--format" }]
 *
 * // Get suggestions after parsing some arguments
-* const suggestions2 = suggestSync(parser, ["-v", "--format="]);
+* const suggestions2 = suggest(parser, ["-v", "--format="]);
 * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
 * ```
 * @since 0.6.0
-* @since 0.9.0 Renamed from the original `suggest` function.
 */
-function suggestSync(parser, args) {
+function suggest(parser, args) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	let context = {
@@ -177,73 +95,6 @@ function suggestSync(parser, args) {
 	return Array.from(parser.suggest(context, prefix));
 }
 /**
-* Generates command-line suggestions based on current parsing state.
-* This function processes the input arguments up to the last argument,
-* then calls the parser's suggest method with the remaining prefix.
-*
-* This function accepts any parser (sync or async) and always returns a Promise.
-* For synchronous suggestion generation with sync parsers, use
-* {@link suggestSync} instead.
-*
-* @template T The type of the value produced by the parser.
-* @param parser The {@link Parser} to use for generating suggestions.
-* @param args The array of command-line arguments including the partial
-*             argument to complete.  The last element is treated as
-*             the prefix for suggestions.
-* @returns A Promise that resolves to an array of {@link Suggestion} objects
-*          containing completion candidates.
-* @since 0.9.0
-*/
-async function suggestAsync(parser, args) {
-	const allButLast = args.slice(0, -1);
-	const prefix = args[args.length - 1];
-	let context = {
-		buffer: allButLast,
-		optionsTerminated: false,
-		state: parser.initialState,
-		usage: parser.usage
-	};
-	while (context.buffer.length > 0) {
-		const result = await parser.parse(context);
-		if (!result.success) {
-			const suggestions$1 = [];
-			for await (const suggestion of parser.suggest(context, prefix)) suggestions$1.push(suggestion);
-			return suggestions$1;
-		}
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
-	}
-	const suggestions = [];
-	for await (const suggestion of parser.suggest(context, prefix)) suggestions.push(suggestion);
-	return suggestions;
-}
-/**
-* Generates command-line suggestions based on current parsing state.
-* This function processes the input arguments up to the last argument,
-* then calls the parser's suggest method with the remaining prefix.
-*
-* The return type depends on the parser's mode:
-* - Sync parsers return `readonly Suggestion[]` directly.
-* - Async parsers return `Promise<readonly Suggestion[]>`.
-*
-* For explicit control, use {@link suggestSync} or {@link suggestAsync}.
-*
-* @template M The execution mode of the parser.
-* @template T The type of the value produced by the parser.
-* @param parser The {@link Parser} to use for generating suggestions.
-* @param args The array of command-line arguments including the partial
-*             argument to complete.  The last element is treated as
-*             the prefix for suggestions.
-* @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
-*          (for async) containing completion candidates.
-* @since 0.6.0
-*/
-function suggest(parser, args) {
-	if (parser.$mode === "async") return suggestAsync(parser, args);
-	return suggestSync(parser, args);
-}
-/**
 * Recursively searches for a command within nested exclusive usage terms.
 * When the command is found, returns the expanded usage terms for that command.
 *
@@ -264,44 +115,39 @@ function findCommandInExclusive(term, commandName) {
 	return null;
 }
 /**
-* Generates a documentation page for a synchronous parser.
+* 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.
+*
+* 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
+*
+* @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.
 *
-* 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
-*/
-function getDocPageSync(parser, args = []) {
-	return getDocPageSyncImpl(parser, args);
-}
-/**
-* Generates a documentation page for any parser, returning a Promise.
+* @example
+* ```typescript
+* const parser = object({
+*   verbose: option("-v", "--verbose"),
+*   port: option("-p", "--port", integer())
+* });
 *
-* 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 for the root parser
+* const rootDoc = getDocPage(parser);
 *
-* @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
+* // Get documentation after parsing some arguments
+* const contextDoc = getDocPage(parser, ["-v"]);
+* ```
 */
-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,
@@ -313,30 +159,6 @@ function getDocPageSyncImpl(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
@@ -380,8 +202,6 @@ 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;
@@ -392,11 +212,7 @@ exports.option = require_primitives.option;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = parse;
-exports.parseAsync = parseAsync;
-exports.parseSync = parseSync;
 exports.passThrough = require_primitives.passThrough;
 exports.suggest = suggest;
-exports.suggestAsync = suggestAsync;
-exports.suggestSync = suggestSync;
 exports.tuple = require_constructs.tuple;
 exports.withDefault = require_modifiers.withDefault;

package/dist/parser.d.cts

@@ -8,46 +8,6 @@ import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, Long
 
 //#region src/parser.d.ts
 
-/**
- * Represents the execution mode for parsers.
- *
- * - `"sync"`: Synchronous execution where methods return values directly.
- * - `"async"`: Asynchronous execution where methods return Promises or
- *   AsyncIterables.
- *
- * @since 0.9.0
- */
-type Mode = "sync" | "async";
-/**
- * Wraps a value type based on the execution mode.
- *
- * - In sync mode: Returns `T` directly.
- * - In async mode: Returns `Promise<T>`.
- *
- * @template M The execution mode.
- * @template T The value type to wrap.
- * @since 0.9.0
- */
-type ModeValue<M extends Mode, T> = M extends "async" ? Promise<T> : T;
-/**
- * Wraps an iterable type based on the execution mode.
- *
- * - In sync mode: Returns `Iterable<T>`.
- * - In async mode: Returns `AsyncIterable<T>`.
- *
- * @template M The execution mode.
- * @template T The element type.
- * @since 0.9.0
- */
-type ModeIterable<M extends Mode, T> = M extends "async" ? AsyncIterable<T> : Iterable<T>;
-/**
- * Combines multiple modes into a single mode.
- * If any mode is `"async"`, the result is `"async"`; otherwise `"sync"`.
- *
- * @template T A tuple of Mode types.
- * @since 0.9.0
- */
-type CombineModes<T extends readonly Mode[]> = "async" extends T[number] ? "async" : "sync";
 /**
  * Represents the state passed to getDocFragments.
  * Can be either the actual parser state or an explicit indicator
@@ -63,12 +23,10 @@ type DocState<TState> = {
 };
 /**
  * Parser interface for command-line argument parsing.
- * @template M The execution mode of the parser (`"sync"` or `"async"`).
  * @template TValue The type of the value returned by the parser.
  * @template TState The type of the state used during parsing.
- * @since 0.9.0 Added the `M` type parameter for sync/async mode support.
  */
-interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
+interface Parser<TValue, TState> {
   /**
    * A type tag for the result value of this parser, used for type inference.
    * Usually this is an empty array at runtime, but it does not matter
@@ -83,15 +41,6 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @internal
    */
   readonly $stateType: readonly TState[];
-  /**
-   * The execution mode of this parser.
-   *
-   * - `"sync"`: All methods return values directly.
-   * - `"async"`: Methods return Promises or AsyncIterables.
-   *
-   * @since 0.9.0
-   */
-  readonly $mode: M;
   /**
    * The priority of this parser, which determines the order in which
    * parsers are applied when multiple parsers are available.  The greater
@@ -114,9 +63,8 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @param context The context of the parser, which includes the input buffer
    *                and the current state.
    * @returns A result object indicating success or failure.
-   *          In async mode, returns a Promise that resolves to the result.
    */
-  parse(context: ParserContext<TState>): ModeValue<M, ParserResult<TState>>;
+  parse(context: ParserContext<TState>): ParserResult<TState>;
   /**
    * Transforms a {@link TState} into a {@link TValue}, if applicable.
    * If the transformation is not applicable, it should return
@@ -128,9 +76,8 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    *          the transformation.  If successful, it should contain
    *          the parsed value of type {@link TValue}.  If not applicable,
    *          it should return an error message.
-   *          In async mode, returns a Promise that resolves to the result.
    */
-  complete(state: TState): ModeValue<M, ValueParserResult<TValue>>;
+  complete(state: TState): ValueParserResult<TValue>;
   /**
    * Generates next-step suggestions based on the current context
    * and an optional prefix.  This can be used to provide shell completion
@@ -141,10 +88,9 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    *               Can be an empty string if no prefix is provided.
    * @returns An iterable of {@link Suggestion} objects, each containing
    *          a suggestion text and an optional description.
-   *          In async mode, returns an AsyncIterable.
    * @since 0.6.0
    */
-  suggest(context: ParserContext<TState>, prefix: string): ModeIterable<M, Suggestion>;
+  suggest(context: ParserContext<TState>, prefix: string): Iterable<Suggestion>;
   /**
    * Generates a documentation fragment for this parser, which can be used
    * to describe the parser's usage, description, and default value.
@@ -271,13 +217,7 @@ type ParserResult<TState> = {
  * Infers the result value type of a {@link Parser}.
  * @template T The {@link Parser} to infer the result value type from.
  */
-type InferValue<T extends Parser<Mode, unknown, unknown>> = T["$valueType"][number];
-/**
- * Infers the execution mode of a {@link Parser}.
- * @template T The {@link Parser} to infer the execution mode from.
- * @since 0.9.0
- */
-type InferMode<T extends Parser<Mode, unknown, unknown>> = T["$mode"];
+type InferValue<T extends Parser<unknown, unknown>> = T["$valueType"][number];
 /**
  * The result type of a whole parser operation, which can either be a successful
  * result with a value of type `T`, or a failure with an error message.
@@ -308,73 +248,23 @@ type Result<T> = {
  * Parses an array of command-line arguments using the provided combined parser.
  * This function processes the input arguments, applying the parser to each
  * argument until all arguments are consumed or an error occurs.
- *
- * This function only accepts synchronous parsers. For asynchronous parsers,
- * use {@link parseAsync}.
- *
  * @template T The type of the value produced by the parser.
  * @param parser The combined {@link Parser} to use for parsing the input
- *               arguments.  Must be a synchronous parser.
+ *               arguments.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
  * @returns A {@link Result} object indicating whether the parsing was
  *          successful or not.  If successful, it contains the parsed value of
  *          type `T`.  If not, it contains an error message describing the
  *          failure.
- * @since 0.9.0 Renamed from the original `parse` function which now delegates
- *              to this for sync parsers.
- */
-declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly string[]): Result<T>;
-/**
- * Parses an array of command-line arguments using the provided combined parser.
- * This function processes the input arguments, applying the parser to each
- * argument until all arguments are consumed or an error occurs.
- *
- * This function accepts any parser (sync or async) and always returns a Promise.
- * For synchronous parsing with sync parsers, use {@link parseSync} instead.
- *
- * @template T The type of the value produced by the parser.
- * @param parser The combined {@link Parser} to use for parsing the input
- *               arguments.
- * @param args The array of command-line arguments to parse.  Usually this is
- *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
- * @returns A Promise that resolves to a {@link Result} object indicating
- *          whether the parsing was successful or not.
- * @since 0.9.0
- */
-declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly string[]): Promise<Result<T>>;
-/**
- * Parses an array of command-line arguments using the provided combined parser.
- * This function processes the input arguments, applying the parser to each
- * argument until all arguments are consumed or an error occurs.
- *
- * The return type depends on the parser's mode:
- * - Sync parsers return `Result<T>` directly.
- * - Async parsers return `Promise<Result<T>>`.
- *
- * For explicit control, use {@link parseSync} or {@link parseAsync}.
- *
- * @template M The execution mode of the parser.
- * @template T The type of the value produced by the parser.
- * @param parser The combined {@link Parser} to use for parsing the input
- *               arguments.
- * @param args The array of command-line arguments to parse.  Usually this is
- *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
- * @returns A {@link Result} object (for sync) or Promise thereof (for async)
- *          indicating whether the parsing was successful or not.
  */
-declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[]): ModeValue<M, Result<T>>;
+declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]): Result<T>;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
  * then calls the parser's suggest method with the remaining prefix.
- *
- * This function only accepts synchronous parsers. For asynchronous parsers,
- * use {@link suggestAsync}.
- *
  * @template T The type of the value produced by the parser.
  * @param parser The {@link Parser} to use for generating suggestions.
- *               Must be a synchronous parser.
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
@@ -388,84 +278,16 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * });
  *
  * // Get suggestions for options starting with "--"
- * const suggestions = suggestSync(parser, ["--"]);
+ * const suggestions = suggest(parser, ["--"]);
  * // Returns: [{ text: "--verbose" }, { text: "--format" }]
  *
  * // Get suggestions after parsing some arguments
- * const suggestions2 = suggestSync(parser, ["-v", "--format="]);
+ * const suggestions2 = suggest(parser, ["-v", "--format="]);
  * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
  * ```
  * @since 0.6.0
- * @since 0.9.0 Renamed from the original `suggest` function.
- */
-declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]]): readonly Suggestion[];
-/**
- * Generates command-line suggestions based on current parsing state.
- * This function processes the input arguments up to the last argument,
- * then calls the parser's suggest method with the remaining prefix.
- *
- * This function accepts any parser (sync or async) and always returns a Promise.
- * For synchronous suggestion generation with sync parsers, use
- * {@link suggestSync} instead.
- *
- * @template T The type of the value produced by the parser.
- * @param parser The {@link Parser} to use for generating suggestions.
- * @param args The array of command-line arguments including the partial
- *             argument to complete.  The last element is treated as
- *             the prefix for suggestions.
- * @returns A Promise that resolves to an array of {@link Suggestion} objects
- *          containing completion candidates.
- * @since 0.9.0
- */
-declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly [string, ...readonly string[]]): Promise<readonly Suggestion[]>;
-/**
- * Generates command-line suggestions based on current parsing state.
- * This function processes the input arguments up to the last argument,
- * then calls the parser's suggest method with the remaining prefix.
- *
- * The return type depends on the parser's mode:
- * - Sync parsers return `readonly Suggestion[]` directly.
- * - Async parsers return `Promise<readonly Suggestion[]>`.
- *
- * For explicit control, use {@link suggestSync} or {@link suggestAsync}.
- *
- * @template M The execution mode of the parser.
- * @template T The type of the value produced by the parser.
- * @param parser The {@link Parser} to use for generating suggestions.
- * @param args The array of command-line arguments including the partial
- *             argument to complete.  The last element is treated as
- *             the prefix for suggestions.
- * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
- *          (for async) containing completion candidates.
- * @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>;
+declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string, ...readonly string[]]): readonly Suggestion[];
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -477,16 +299,13 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, 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 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.
+ * @returns A {@link DocPage} containing usage information, sections, and
+ *          optional description, or `undefined` if no documentation can be
+ *          generated.
  *
  * @example
  * ```typescript
@@ -495,16 +314,13 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  *   port: option("-p", "--port", integer())
  * });
  *
- * // Get documentation for sync parser
+ * // Get documentation for the root parser
  * const rootDoc = getDocPage(parser);
  *
- * // Get documentation for async parser
- * const asyncDoc = await getDocPage(asyncParser);
+ * // Get documentation after parsing some arguments
+ * const contextDoc = getDocPage(parser, ["-v"]);
  * ```
- * @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>;
+declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): 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, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, 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, passThrough, suggest, tuple, withDefault };