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

package/dist/parser.cjs

@@ -9,17 +9,23 @@ 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.
+*               arguments.  Must be a synchronous parser.
 * @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 parse(parser, args) {
+function parseSync(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -49,11 +55,86 @@ function parse(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.
@@ -67,16 +148,17 @@ function parse(parser, args) {
 * });
 *
 * // Get suggestions for options starting with "--"
-* const suggestions = suggest(parser, ["--"]);
+* const suggestions = suggestSync(parser, ["--"]);
 * // Returns: [{ text: "--verbose" }, { text: "--format" }]
 *
 * // Get suggestions after parsing some arguments
-* const suggestions2 = suggest(parser, ["-v", "--format="]);
+* const suggestions2 = suggestSync(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 suggest(parser, args) {
+function suggestSync(parser, args) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	let context = {
@@ -95,6 +177,93 @@ function suggest(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.
+*
+* @param term The usage term to search in
+* @param commandName The command name to find
+* @returns The expanded usage terms if found, null otherwise
+*/
+function findCommandInExclusive(term, commandName) {
+	if (term.type !== "exclusive") return null;
+	for (const termGroup of term.terms) {
+		const firstTerm = termGroup[0];
+		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
+		if (firstTerm?.type === "exclusive") {
+			const found = findCommandInExclusive(firstTerm, commandName);
+			if (found) return [...found, ...termGroup.slice(1)];
+		}
+	}
+	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.
@@ -157,14 +326,11 @@ function getDocPage(parser, args = []) {
 		if (i >= usage.length) break;
 		const term = usage[i];
 		if (term.type === "exclusive") {
-			for (const termGroup of term.terms) {
-				const firstTerm = termGroup[0];
-				if (firstTerm?.type !== "command" || firstTerm.name !== arg) continue;
-				usage.splice(i, 1, ...termGroup);
-				i += termGroup.length;
-				break;
-			}
-			if (usage[i] === term) i++;
+			const found = findCommandInExclusive(term, arg);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				i += found.length;
+			} else i++;
 		} else i++;
 	}
 	return {
@@ -195,7 +361,11 @@ 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,6 +8,46 @@ 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
@@ -23,10 +63,12 @@ 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<TValue, TState> {
+interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
   /**
    * 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
@@ -41,6 +83,15 @@ interface Parser<TValue, TState> {
    * @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
@@ -63,8 +114,9 @@ interface Parser<TValue, TState> {
    * @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>): ParserResult<TState>;
+  parse(context: ParserContext<TState>): ModeValue<M, ParserResult<TState>>;
   /**
    * Transforms a {@link TState} into a {@link TValue}, if applicable.
    * If the transformation is not applicable, it should return
@@ -76,8 +128,9 @@ interface Parser<TValue, TState> {
    *          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): ValueParserResult<TValue>;
+  complete(state: TState): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Generates next-step suggestions based on the current context
    * and an optional prefix.  This can be used to provide shell completion
@@ -88,9 +141,10 @@ interface Parser<TValue, TState> {
    *               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): Iterable<Suggestion>;
+  suggest(context: ParserContext<TState>, prefix: string): ModeIterable<M, Suggestion>;
   /**
    * Generates a documentation fragment for this parser, which can be used
    * to describe the parser's usage, description, and default value.
@@ -217,7 +271,13 @@ 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<unknown, unknown>> = T["$valueType"][number];
+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"];
 /**
  * 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.
@@ -248,23 +308,73 @@ 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.
+ *               arguments.  Must be a synchronous parser.
  * @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 parse<T>(parser: Parser<T, unknown>, args: readonly string[]): Result<T>;
+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>>;
 /**
  * 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.
@@ -278,16 +388,58 @@ declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]):
  * });
  *
  * // Get suggestions for options starting with "--"
- * const suggestions = suggest(parser, ["--"]);
+ * const suggestions = suggestSync(parser, ["--"]);
  * // Returns: [{ text: "--verbose" }, { text: "--format" }]
  *
  * // Get suggestions after parsing some arguments
- * const suggestions2 = suggest(parser, ["-v", "--format="]);
+ * const suggestions2 = suggestSync(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<T>(parser: Parser<T, unknown>, args: readonly [string, ...readonly string[]]): readonly Suggestion[];
+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 parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -321,6 +473,6 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  * const contextDoc = getDocPage(parser, ["-v"]);
  * ```
  */
-declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-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 };
+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 };