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

package/dist/primitives.cjs

@@ -13,6 +13,7 @@ function constant(value) {
 	return {
 		$valueType: [],
 		$stateType: [],
+		$mode: "sync",
 		priority: 0,
 		usage: [],
 		initialState: value,
@@ -37,6 +38,112 @@ function constant(value) {
 		}
 	};
 }
+/**
+* Internal sync helper for option suggest functionality.
+* @internal
+*/
+function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix) {
+	if (hidden) return;
+	const equalsIndex = prefix.indexOf("=");
+	if (equalsIndex >= 0) {
+		const optionPart = prefix.slice(0, equalsIndex);
+		const valuePart = prefix.slice(equalsIndex + 1);
+		if (optionNames$1.includes(optionPart)) {
+			if (valueParser && valueParser.suggest) {
+				const valueSuggestions = valueParser.suggest(valuePart);
+				for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
+					kind: "literal",
+					text: `${optionPart}=${suggestion.text}`,
+					description: suggestion.description
+				};
+				else yield {
+					kind: "literal",
+					text: `${optionPart}=${suggestion.pattern || ""}`,
+					description: suggestion.description
+				};
+			}
+		}
+	} else {
+		if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+				if (prefix === "-" && optionName$1.length !== 2) continue;
+				yield {
+					kind: "literal",
+					text: optionName$1
+				};
+			}
+		}
+		if (valueParser && valueParser.suggest) {
+			let shouldSuggestValues = false;
+			if (context.buffer.length > 0) {
+				const lastToken = context.buffer[context.buffer.length - 1];
+				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
+			} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
+			if (shouldSuggestValues) yield* valueParser.suggest(prefix);
+		}
+	}
+}
+/**
+* Internal async helper for option suggest functionality.
+* @internal
+*/
+async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context, prefix) {
+	if (hidden) return;
+	const equalsIndex = prefix.indexOf("=");
+	if (equalsIndex >= 0) {
+		const optionPart = prefix.slice(0, equalsIndex);
+		const valuePart = prefix.slice(equalsIndex + 1);
+		if (optionNames$1.includes(optionPart)) {
+			if (valueParser && valueParser.suggest) {
+				const valueSuggestions = valueParser.suggest(valuePart);
+				for await (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
+					kind: "literal",
+					text: `${optionPart}=${suggestion.text}`,
+					description: suggestion.description
+				};
+				else yield {
+					kind: "literal",
+					text: `${optionPart}=${suggestion.pattern || ""}`,
+					description: suggestion.description
+				};
+			}
+		}
+	} else {
+		if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+				if (prefix === "-" && optionName$1.length !== 2) continue;
+				yield {
+					kind: "literal",
+					text: optionName$1
+				};
+			}
+		}
+		if (valueParser && valueParser.suggest) {
+			let shouldSuggestValues = false;
+			if (context.buffer.length > 0) {
+				const lastToken = context.buffer[context.buffer.length - 1];
+				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
+			} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
+			if (shouldSuggestValues) for await (const suggestion of valueParser.suggest(prefix)) yield suggestion;
+		}
+	}
+}
+/**
+* Internal sync helper for argument suggest functionality.
+* @internal
+*/
+function* suggestArgumentSync(valueParser, hidden, prefix) {
+	if (hidden) return;
+	if (valueParser.suggest) yield* valueParser.suggest(prefix);
+}
+/**
+* Internal async helper for argument suggest functionality.
+* @internal
+*/
+async function* suggestArgumentAsync(valueParser, hidden, prefix) {
+	if (hidden) return;
+	if (valueParser.suggest) for await (const suggestion of valueParser.suggest(prefix)) yield suggestion;
+}
 function option(...args) {
 	const lastArg = args.at(-1);
 	const secondLastArg = args.at(-2);
@@ -59,7 +166,10 @@ function option(...args) {
 		optionNames$1 = args;
 		valueParser = void 0;
 	}
-	return {
+	const mode = valueParser?.$mode ?? "sync";
+	const isAsync = mode === "async";
+	const result = {
+		$mode: mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 10,
@@ -105,7 +215,7 @@ function option(...args) {
 				consumed: context.buffer.slice(0, 1)
 			};
 			if (optionNames$1.includes(context.buffer[0])) {
-				if (context.state.success && (valueParser != null || context.state.value)) return {
+				if (context.state?.success && (valueParser != null || context.state.value)) return {
 					success: false,
 					consumed: 1,
 					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(context.buffer[0]) : options.errors.duplicate : require_message.message`${require_message.optionName(context.buffer[0])} cannot be used multiple times.`
@@ -127,12 +237,21 @@ function option(...args) {
 					consumed: 1,
 					error: require_message.message`Option ${require_message.optionName(context.buffer[0])} requires a value, but got no value.`
 				};
-				const result = valueParser.parse(context.buffer[1]);
+				const parseResultOrPromise = valueParser.parse(context.buffer[1]);
+				if (isAsync) return parseResultOrPromise.then((parseResult) => ({
+					success: true,
+					next: {
+						...context,
+						state: parseResult,
+						buffer: context.buffer.slice(2)
+					},
+					consumed: context.buffer.slice(0, 2)
+				}));
 				return {
 					success: true,
 					next: {
 						...context,
-						state: result,
+						state: parseResultOrPromise,
 						buffer: context.buffer.slice(2)
 					},
 					consumed: context.buffer.slice(0, 2)
@@ -141,7 +260,7 @@ function option(...args) {
 			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/")).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) {
 				if (!context.buffer[0].startsWith(prefix)) continue;
-				if (context.state.success && (valueParser != null || context.state.value)) return {
+				if (context.state?.success && (valueParser != null || context.state.value)) return {
 					success: false,
 					consumed: 1,
 					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : require_message.message`${require_message.optionName(prefix)} cannot be used multiple times.`
@@ -152,12 +271,21 @@ function option(...args) {
 					consumed: 1,
 					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(value) : options.errors.unexpectedValue : require_message.message`Option ${require_message.optionName(prefix)} is a Boolean flag, but got a value: ${value}.`
 				};
-				const result = valueParser.parse(value);
+				const parseResultOrPromise = valueParser.parse(value);
+				if (isAsync) return parseResultOrPromise.then((parseResult) => ({
+					success: true,
+					next: {
+						...context,
+						state: parseResult,
+						buffer: context.buffer.slice(1)
+					},
+					consumed: context.buffer.slice(0, 1)
+				}));
 				return {
 					success: true,
 					next: {
 						...context,
-						state: result,
+						state: parseResultOrPromise,
 						buffer: context.buffer.slice(1)
 					},
 					consumed: context.buffer.slice(0, 1)
@@ -167,7 +295,7 @@ function option(...args) {
 				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
 				for (const shortOption of shortOptions) {
 					if (!context.buffer[0].startsWith(shortOption)) continue;
-					if (context.state.success && (valueParser != null || context.state.value)) return {
+					if (context.state?.success && (valueParser != null || context.state.value)) return {
 						success: false,
 						consumed: 1,
 						error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(shortOption) : options.errors.duplicate : require_message.message`${require_message.optionName(shortOption)} cannot be used multiple times.`
@@ -220,50 +348,8 @@ function option(...args) {
 			};
 		},
 		suggest(context, prefix) {
-			if (options.hidden) return [];
-			const suggestions = [];
-			const equalsIndex = prefix.indexOf("=");
-			if (equalsIndex >= 0) {
-				const optionPart = prefix.slice(0, equalsIndex);
-				const valuePart = prefix.slice(equalsIndex + 1);
-				if (optionNames$1.includes(optionPart)) {
-					if (valueParser && valueParser.suggest) {
-						const valueSuggestions = valueParser.suggest(valuePart);
-						for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") suggestions.push({
-							kind: "literal",
-							text: `${optionPart}=${suggestion.text}`,
-							description: suggestion.description
-						});
-						else suggestions.push({
-							kind: "literal",
-							text: `${optionPart}=${suggestion.pattern || ""}`,
-							description: suggestion.description
-						});
-					}
-				}
-			} else {
-				if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
-					for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-						if (prefix === "-" && optionName$1.length !== 2) continue;
-						suggestions.push({
-							kind: "literal",
-							text: optionName$1
-						});
-					}
-				}
-				if (valueParser && valueParser.suggest) {
-					let shouldSuggestValues = false;
-					if (context.buffer.length > 0) {
-						const lastToken = context.buffer[context.buffer.length - 1];
-						if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-					} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
-					if (shouldSuggestValues) {
-						const valueSuggestions = valueParser.suggest(prefix);
-						suggestions.push(...valueSuggestions);
-					}
-				}
-			}
-			return suggestions;
+			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
+			return suggestOptionSync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
 			if (options.hidden) return {
@@ -289,6 +375,7 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	return result;
 }
 /**
 * Creates a parser for command-line flags that must be explicitly provided.
@@ -332,6 +419,7 @@ function flag(...args) {
 	return {
 		$valueType: [],
 		$stateType: [],
+		$mode: "sync",
 		priority: 10,
 		usage: [{
 			type: "option",
@@ -483,6 +571,7 @@ function flag(...args) {
 * Creates a parser that expects a single argument value.
 * This parser is typically used for positional arguments
 * that are not options or flags.
+* @template M The execution mode of the parser.
 * @template T The type of the value produced by the parser.
 * @param valueParser The {@link ValueParser} that defines how to parse
 *                    the argument value.
@@ -492,13 +581,15 @@ function flag(...args) {
 *          the parsed value of type {@link T}.
 */
 function argument(valueParser, options = {}) {
+	const isAsync = valueParser.$mode === "async";
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
 		metavar: valueParser.metavar,
 		...options.hidden && { hidden: true }
 	};
-	return {
+	const result = {
+		$mode: valueParser.$mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 5,
@@ -532,13 +623,23 @@ function argument(valueParser, options = {}) {
 				consumed: i,
 				error: options.errors?.multiple ? typeof options.errors.multiple === "function" ? options.errors.multiple(valueParser.metavar) : options.errors.multiple : require_message.message`The argument ${require_message.metavar(valueParser.metavar)} cannot be used multiple times.`
 			};
-			const result = valueParser.parse(context.buffer[i]);
+			const parseResultOrPromise = valueParser.parse(context.buffer[i]);
+			if (isAsync) return parseResultOrPromise.then((parseResult) => ({
+				success: true,
+				next: {
+					...context,
+					buffer: context.buffer.slice(i + 1),
+					state: parseResult,
+					optionsTerminated
+				},
+				consumed: context.buffer.slice(0, i + 1)
+			}));
 			return {
 				success: true,
 				next: {
 					...context,
 					buffer: context.buffer.slice(i + 1),
-					state: result,
+					state: parseResultOrPromise,
 					optionsTerminated
 				},
 				consumed: context.buffer.slice(0, i + 1)
@@ -556,13 +657,8 @@ function argument(valueParser, options = {}) {
 			};
 		},
 		suggest(_context, prefix) {
-			if (options.hidden) return [];
-			const suggestions = [];
-			if (valueParser.suggest) {
-				const valueSuggestions = valueParser.suggest(prefix);
-				suggestions.push(...valueSuggestions);
-			}
-			return suggestions;
+			if (isAsync) return suggestArgumentAsync(valueParser, options.hidden ?? false, prefix);
+			return suggestArgumentSync(valueParser, options.hidden ?? false, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
 			if (options.hidden) return {
@@ -584,11 +680,52 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	return result;
+}
+function* suggestCommandSync(context, prefix, name, parser, options) {
+	if (options.hidden) return;
+	if (context.state === void 0) {
+		if (name.startsWith(prefix)) yield {
+			kind: "literal",
+			text: name,
+			...options.description && { description: options.description }
+		};
+	} else if (context.state[0] === "matched") yield* parser.suggest({
+		...context,
+		state: parser.initialState
+	}, prefix);
+	else if (context.state[0] === "parsing") yield* parser.suggest({
+		...context,
+		state: context.state[1]
+	}, prefix);
+}
+async function* suggestCommandAsync(context, prefix, name, parser, options) {
+	if (options.hidden) return;
+	if (context.state === void 0) {
+		if (name.startsWith(prefix)) yield {
+			kind: "literal",
+			text: name,
+			...options.description && { description: options.description }
+		};
+	} else if (context.state[0] === "matched") {
+		const suggestions = parser.suggest({
+			...context,
+			state: parser.initialState
+		}, prefix);
+		for await (const s of suggestions) yield s;
+	} else if (context.state[0] === "parsing") {
+		const suggestions = parser.suggest({
+			...context,
+			state: context.state[1]
+		}, prefix);
+		for await (const s of suggestions) yield s;
+	}
 }
 /**
 * Creates a parser that matches a specific subcommand name and then applies
 * an inner parser to the remaining arguments.
 * This is useful for building CLI tools with subcommands like git, npm, etc.
+* @template M The execution mode of the parser.
 * @template T The type of the value returned by the inner parser.
 * @template TState The type of the state used by the inner parser.
 * @param name The subcommand name to match (e.g., `"show"`, `"edit"`).
@@ -599,7 +736,9 @@ function argument(valueParser, options = {}) {
 *          to the inner parser for the remaining arguments.
 */
 function command(name, parser, options = {}) {
-	return {
+	const isAsync = parser.$mode === "async";
+	const result = {
+		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 15,
@@ -646,33 +785,57 @@ function command(name, parser, options = {}) {
 					consumed: context.buffer.slice(0, 1)
 				};
 			} else if (context.state[0] === "matched") {
-				const result = parser.parse({
+				const parseResultOrPromise = parser.parse({
 					...context,
 					state: parser.initialState
 				});
-				if (result.success) return {
+				if (isAsync) return parseResultOrPromise.then((parseResult$1) => {
+					if (parseResult$1.success) return {
+						success: true,
+						next: {
+							...parseResult$1.next,
+							state: ["parsing", parseResult$1.next.state]
+						},
+						consumed: parseResult$1.consumed
+					};
+					return parseResult$1;
+				});
+				const parseResult = parseResultOrPromise;
+				if (parseResult.success) return {
 					success: true,
 					next: {
-						...result.next,
-						state: ["parsing", result.next.state]
+						...parseResult.next,
+						state: ["parsing", parseResult.next.state]
 					},
-					consumed: result.consumed
+					consumed: parseResult.consumed
 				};
-				return result;
+				return parseResult;
 			} else if (context.state[0] === "parsing") {
-				const result = parser.parse({
+				const parseResultOrPromise = parser.parse({
 					...context,
 					state: context.state[1]
 				});
-				if (result.success) return {
+				if (isAsync) return parseResultOrPromise.then((parseResult$1) => {
+					if (parseResult$1.success) return {
+						success: true,
+						next: {
+							...parseResult$1.next,
+							state: ["parsing", parseResult$1.next.state]
+						},
+						consumed: parseResult$1.consumed
+					};
+					return parseResult$1;
+				});
+				const parseResult = parseResultOrPromise;
+				if (parseResult.success) return {
 					success: true,
 					next: {
-						...result.next,
-						state: ["parsing", result.next.state]
+						...parseResult.next,
+						state: ["parsing", parseResult.next.state]
 					},
-					consumed: result.consumed
+					consumed: parseResult.consumed
 				};
-				return result;
+				return parseResult;
 			}
 			return {
 				success: false,
@@ -693,28 +856,8 @@ function command(name, parser, options = {}) {
 			};
 		},
 		suggest(context, prefix) {
-			if (options.hidden) return [];
-			const suggestions = [];
-			if (context.state === void 0) {
-				if (name.startsWith(prefix)) suggestions.push({
-					kind: "literal",
-					text: name,
-					...options.description && { description: options.description }
-				});
-			} else if (context.state[0] === "matched") {
-				const innerSuggestions = parser.suggest({
-					...context,
-					state: parser.initialState
-				}, prefix);
-				suggestions.push(...innerSuggestions);
-			} else if (context.state[0] === "parsing") {
-				const innerSuggestions = parser.suggest({
-					...context,
-					state: context.state[1]
-				}, prefix);
-				suggestions.push(...innerSuggestions);
-			}
-			return suggestions;
+			if (isAsync) return suggestCommandAsync(context, prefix, name, parser, options);
+			return suggestCommandSync(context, prefix, name, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
 			if (options.hidden) return {
@@ -750,6 +893,7 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	return result;
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -804,6 +948,7 @@ function passThrough(options = {}) {
 	return {
 		$valueType: [],
 		$stateType: [],
+		$mode: "sync",
 		priority: -10,
 		usage: [{
 			type: "passthrough",

package/dist/primitives.d.cts

@@ -1,7 +1,7 @@
 import { Message } from "./message.cjs";
 import { OptionName } from "./usage.cjs";
 import { ValueParser, ValueParserResult } from "./valueparser.cjs";
-import { Parser } from "./parser.cjs";
+import { Mode, Parser } from "./parser.cjs";
 
 //#region src/primitives.d.ts
 
@@ -10,7 +10,7 @@ import { Parser } from "./parser.cjs";
  * produces a constant value of the type {@link T}.
  * @template T The type of the constant value produced by the parser.
  */
-declare function constant<const T>(value: T): Parser<T, T>;
+declare function constant<const T>(value: T): Parser<"sync", T, T>;
 /**
  * Options for the {@link option} parser.
  */
@@ -78,6 +78,7 @@ interface OptionErrorOptions {
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
  *             a {@link ValueParser} that defines how to parse the value of
@@ -86,10 +87,11 @@ interface OptionErrorOptions {
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<T>(...args: readonly [...readonly OptionName[], ValueParser<T>]): Parser<T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
  *             a {@link ValueParser} that defines how to parse the value of
@@ -98,7 +100,7 @@ declare function option<T>(...args: readonly [...readonly OptionName[], ValuePar
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<T>(...args: readonly [...readonly OptionName[], ValueParser<T>, OptionOptions]): Parser<T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [...readonly OptionName[], ValueParser<M, T>, OptionOptions]): Parser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that do not
  * take an argument value, such as `--option`, `-o`, or `/option`.
@@ -106,7 +108,7 @@ declare function option<T>(...args: readonly [...readonly OptionName[], ValuePar
  * @return A {@link Parser} that can parse the specified options as Boolean
  *         flags, producing `true` if the option is present.
  */
-declare function option(...optionNames: readonly OptionName[]): Parser<boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...optionNames: readonly OptionName[]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-o value`, or `/option:value`.
@@ -116,7 +118,7 @@ declare function option(...optionNames: readonly OptionName[]): Parser<boolean,
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option(...args: readonly [...readonly OptionName[], OptionOptions]): Parser<boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...args: readonly [...readonly OptionName[], OptionOptions]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Options for the {@link flag} parser.
  */
@@ -202,7 +204,7 @@ interface FlagErrorOptions {
  * });
  * ```
  */
-declare function flag(...args: readonly [...readonly OptionName[], FlagOptions] | readonly OptionName[]): Parser<true, ValueParserResult<true> | undefined>;
+declare function flag(...args: readonly [...readonly OptionName[], FlagOptions] | readonly OptionName[]): Parser<"sync", true, ValueParserResult<true> | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -248,6 +250,7 @@ interface ArgumentErrorOptions {
  * Creates a parser that expects a single argument value.
  * This parser is typically used for positional arguments
  * that are not options or flags.
+ * @template M The execution mode of the parser.
  * @template T The type of the value produced by the parser.
  * @param valueParser The {@link ValueParser} that defines how to parse
  *                    the argument value.
@@ -256,7 +259,7 @@ interface ArgumentErrorOptions {
  * @returns A {@link Parser} that expects a single argument value and produces
  *          the parsed value of type {@link T}.
  */
-declare function argument<T>(valueParser: ValueParser<T>, options?: ArgumentOptions): Parser<T, ValueParserResult<T> | undefined>;
+declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): Parser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Options for the {@link command} parser.
  * @since 0.5.0
@@ -325,6 +328,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  * Creates a parser that matches a specific subcommand name and then applies
  * an inner parser to the remaining arguments.
  * This is useful for building CLI tools with subcommands like git, npm, etc.
+ * @template M The execution mode of the parser.
  * @template T The type of the value returned by the inner parser.
  * @template TState The type of the state used by the inner parser.
  * @param name The subcommand name to match (e.g., `"show"`, `"edit"`).
@@ -334,7 +338,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  * @returns A {@link Parser} that matches the command name and delegates
  *          to the inner parser for the remaining arguments.
  */
-declare function command<T, TState>(name: string, parser: Parser<T, TState>, options?: CommandOptions): Parser<T, CommandState<TState>>;
+declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): Parser<M, T, CommandState<TState>>;
 /**
  * Format options for how {@link passThrough} captures options.
  * @since 0.8.0
@@ -417,6 +421,6 @@ interface PassThroughOptions {
  *
  * @since 0.8.0
  */
-declare function passThrough(options?: PassThroughOptions): Parser<readonly string[], readonly string[]>;
+declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };