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

package/dist/facade.cjs

@@ -89,6 +89,11 @@ function createCompletionParser(mode, programName, availableShells, name = "both
 		{ description: require_message.message`Generate shell completion script.` }
 	];
 	const completionOption = require_primitives.option(...completionOptionArgs);
+	const argsParser = require_modifiers.withDefault(require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "ARG" }), { description: require_message.message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` })), []);
+	const optionParser = require_constructs.object({
+		shell: completionOption,
+		args: argsParser
+	});
 	switch (mode) {
 		case "command": return {
 			completionCommand,
@@ -96,17 +101,11 @@ function createCompletionParser(mode, programName, availableShells, name = "both
 		};
 		case "option": return {
 			completionCommand: null,
-			completionOption: require_constructs.object({
-				shell: completionOption,
-				args: require_modifiers.withDefault(require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "ARG" }), { description: require_message.message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` })), [])
-			})
+			completionOption: optionParser
 		};
 		case "both": return {
 			completionCommand,
-			completionOption: require_constructs.object({
-				shell: completionOption,
-				args: require_modifiers.withDefault(require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "ARG" }), { description: require_message.message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` })), [])
-			})
+			completionOption: optionParser
 		};
 	}
 }
@@ -117,6 +116,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	const parsers = [];
 	if (helpParsers.helpOption) {
 		const lenientHelpParser = {
+			$mode: "sync",
 			$valueType: [],
 			$stateType: [],
 			priority: 200,
@@ -178,12 +178,11 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 					value: state
 				};
 			},
-			suggest(_context, prefix) {
-				if ("--help".startsWith(prefix)) return [{
+			*suggest(_context, prefix) {
+				if ("--help".startsWith(prefix)) yield {
 					kind: "literal",
 					text: "--help"
-				}];
-				return [];
+				};
 			},
 			getDocFragments(state) {
 				return helpParsers.helpOption?.getDocFragments(state) ?? { fragments: [] };
@@ -193,6 +192,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}
 	if (versionParsers.versionOption) {
 		const lenientVersionParser = {
+			$mode: "sync",
 			$valueType: [],
 			$stateType: [],
 			priority: 200,
@@ -246,12 +246,11 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 					value: state
 				};
 			},
-			suggest(_context, prefix) {
-				if ("--version".startsWith(prefix)) return [{
+			*suggest(_context, prefix) {
+				if ("--version".startsWith(prefix)) yield {
 					kind: "literal",
 					text: "--version"
-				}];
-				return [];
+				};
 			},
 			getDocFragments(state) {
 				return versionParsers.versionOption?.getDocFragments(state) ?? { fragments: [] };
@@ -346,6 +345,20 @@ function classifyResult(result, args) {
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
+	const callOnError = (code) => {
+		try {
+			return onError(code);
+		} catch {
+			return onError();
+		}
+	};
+	const callOnCompletion = (code) => {
+		try {
+			return onCompletion(code);
+		} catch {
+			return onCompletion();
+		}
+	};
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
@@ -355,70 +368,41 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 				maxWidth
 			}));
 		}
-		try {
-			return onError(1);
-		} catch {
-			return onError();
-		}
+		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
+		return callOnError(1);
 	}
 	const shell = availableShells[shellName];
 	if (!shell) {
 		const available = [];
-		for (const shell$1 in availableShells) {
+		for (const name in availableShells) {
 			if (available.length > 0) available.push(require_message.text(", "));
-			available.push(require_message.value(shell$1));
+			available.push(require_message.value(name));
 		}
 		stderr(require_message.formatMessage(require_message.message`Error: Unsupported shell ${shellName}. Available shells: ${available}.`, {
 			colors,
 			quotes: !colors
 		}));
-		return onError(1);
+		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
+		return callOnError(1);
 	}
 	if (args.length === 0) {
 		const usePlural = completionName === "plural";
 		const completionArg = completionMode === "option" ? usePlural ? "--completions" : "--completion" : usePlural ? "completions" : "completion";
 		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
-	} else {
-		const suggestions = require_parser.suggest(parser, args);
-		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
-	}
-	try {
-		return onCompletion(0);
-	} catch {
-		return onCompletion();
+		if (parser.$mode === "async") return Promise.resolve(callOnCompletion(0));
+		return callOnCompletion(0);
 	}
+	if (parser.$mode === "async") return (async () => {
+		const suggestions$1 = await require_parser.suggestAsync(parser, args);
+		for (const chunk of shell.encodeSuggestions(suggestions$1)) stdout(chunk);
+		return callOnCompletion(0);
+	})();
+	const syncParser = parser;
+	const suggestions = require_parser.suggest(syncParser, args);
+	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
+	return callOnCompletion(0);
 }
-/**
-* Runs a parser against command-line arguments with built-in help and error
-* handling.
-*
-* This function provides a complete CLI interface by automatically handling
-* help commands/options and displaying formatted error messages with usage
-* information when parsing fails. It augments the provided parser with help
-* functionality based on the configuration options.
-*
-* The function will:
-*
-* 1. Add help command/option support (unless disabled)
-* 2. Parse the provided arguments
-* 3. Display help if requested
-* 4. Show formatted error messages with usage/help info on parse failures
-* 5. Return the parsed result or invoke the appropriate callback
-*
-* @template TParser The parser type being run.
-* @template THelp Return type when help is shown (defaults to `void`).
-* @template TError Return type when an error occurs (defaults to `never`).
-* @param parser The parser to run against the command-line arguments.
-* @param programName Name of the program used in usage and help output.
-* @param args Command-line arguments to parse (typically from
-*             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
-* @param options Configuration options for output formatting and callbacks.
-* @returns The parsed result value, or the return value of `onHelp`/`onError`
-*          callbacks.
-* @throws {RunParserError} When parsing fails and no `onError` callback is
-*          provided.
-*/
 function runParser(parser, programName, args, options = {}) {
 	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
@@ -480,94 +464,100 @@ function runParser(parser, programName, args, options = {}) {
 		}
 	}
 	const augmentedParser = help === "none" && version === "none" && completion === "none" ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers);
-	const result = require_parser.parse(augmentedParser, args);
-	const classified = classifyResult(result, args);
-	switch (classified.type) {
-		case "success": return classified.value;
-		case "version":
-			stdout(versionValue);
-			try {
-				return onVersion(0);
-			} catch {
-				return onVersion();
-			}
-		case "completion": throw new RunParserError("Completion should be handled by early return");
-		case "help": {
-			let helpGeneratorParser;
-			const helpAsCommand = help === "command" || help === "both";
-			const versionAsCommand = version === "command" || version === "both";
-			const completionAsCommand = completion === "command" || completion === "both";
-			const requestedCommand = classified.commands[0];
-			if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
-			else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
-			else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
-			else {
-				const commandParsers = [parser];
-				if (helpAsCommand) {
-					if (helpParsers.helpCommand) commandParsers.push(helpParsers.helpCommand);
-				}
-				if (versionAsCommand) {
-					if (versionParsers.versionCommand) commandParsers.push(versionParsers.versionCommand);
+	const handleResult = (result) => {
+		const classified = classifyResult(result, args);
+		switch (classified.type) {
+			case "success": return classified.value;
+			case "version":
+				stdout(versionValue);
+				try {
+					return onVersion(0);
+				} catch {
+					return onVersion();
 				}
-				if (completionAsCommand) {
-					if (completionParsers.completionCommand) commandParsers.push(completionParsers.completionCommand);
-				}
-				if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-				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();
-			}
-		}
-		case "error": {
-			if (aboveError === "help") {
-				const doc = require_parser.getDocPage(args.length < 1 ? augmentedParser : parser, args);
-				if (doc == null) aboveError = "usage";
+			case "completion": throw new RunParserError("Completion should be handled by early return");
+			case "help": {
+				let helpGeneratorParser;
+				const helpAsCommand = help === "command" || help === "both";
+				const versionAsCommand = version === "command" || version === "both";
+				const completionAsCommand = completion === "command" || completion === "both";
+				const requestedCommand = classified.commands[0];
+				if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
+				else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
+				else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 				else {
+					const commandParsers = [parser];
+					if (helpAsCommand) {
+						if (helpParsers.helpCommand) commandParsers.push(helpParsers.helpCommand);
+					}
+					if (versionAsCommand) {
+						if (versionParsers.versionCommand) commandParsers.push(versionParsers.versionCommand);
+					}
+					if (completionAsCommand) {
+						if (completionParsers.completionCommand) commandParsers.push(completionParsers.completionCommand);
+					}
+					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
+					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: brief ?? doc.brief,
-						description: description ?? doc.description,
-						footer: footer ?? doc.footer
+						brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
+						description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+						footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
 					};
-					stderr(require_doc.formatDocPage(programName, augmentedDoc, {
+					stdout(require_doc.formatDocPage(programName, augmentedDoc, {
 						colors,
 						maxWidth,
 						showDefault
 					}));
 				}
+				try {
+					return onHelp(0);
+				} catch {
+					return onHelp();
+				}
 			}
-			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);
+			case "error": {
+				if (aboveError === "help") {
+					const doc = require_parser.getDocPage(args.length < 1 ? augmentedParser : parser, args);
+					if (doc == null) aboveError = "usage";
+					else {
+						const augmentedDoc = {
+							...doc,
+							brief: brief ?? doc.brief,
+							description: description ?? doc.description,
+							footer: footer ?? doc.footer
+						};
+						stderr(require_doc.formatDocPage(programName, augmentedDoc, {
+							colors,
+							maxWidth,
+							showDefault
+						}));
+					}
+				}
+				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);
+			}
+			default: throw new RunParserError("Unexpected parse result type");
 		}
-		default: throw new RunParserError("Unexpected parse result type");
+	};
+	if (parser.$mode === "async") return require_parser.parseAsync(augmentedParser, args).then(handleResult);
+	else {
+		const result = require_parser.parseSync(augmentedParser, args);
+		return handleResult(result);
 	}
 }
 /**

package/dist/facade.d.cts

@@ -1,6 +1,6 @@
 import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
-import { InferValue, Parser } from "./parser.cjs";
+import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 
 //#region src/facade.d.ts
@@ -214,7 +214,9 @@ interface RunOptions<THelp, TError> {
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  */
-declare function runParser<TParser extends Parser<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<"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>>;
 /**
  * @deprecated Use `runParser()` instead. This export will be removed in
  *             a future major version. The name `run` conflicts with

package/dist/facade.d.ts

@@ -1,6 +1,6 @@
 import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
-import { InferValue, Parser } from "./parser.js";
+import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
 
 //#region src/facade.d.ts
@@ -214,7 +214,9 @@ interface RunOptions<THelp, TError> {
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  */
-declare function runParser<TParser extends Parser<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<"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>>;
 /**
  * @deprecated Use `runParser()` instead. This export will be removed in
  *             a future major version. The name `run` conflicts with