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

package/dist/modifiers.js

@@ -9,12 +9,31 @@ import { formatMessage, message, text } from "./message.js";
 * - Returning success with undefined state when inner parser fails without consuming
 * @internal
 */
-function parseOptionalStyle(context, parser) {
+function parseOptionalStyleSync(context, parser) {
 	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
 	const result = parser.parse({
 		...context,
 		state: innerState
 	});
+	return processOptionalStyleResult(result, innerState, context);
+}
+/**
+* Internal async helper for optional-style parsing logic.
+* @internal
+*/
+async function parseOptionalStyleAsync(context, parser) {
+	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const result = await parser.parse({
+		...context,
+		state: innerState
+	});
+	return processOptionalStyleResult(result, innerState, context);
+}
+/**
+* Internal helper to process optional-style parse results.
+* @internal
+*/
+function processOptionalStyleResult(result, innerState, context) {
 	if (result.success) {
 		if (result.next.state !== innerState || result.consumed.length === 0) return {
 			success: true,
@@ -45,6 +64,7 @@ function parseOptionalStyle(context, parser) {
 * without consuming input if the wrapped parser fails to match.
 * If the wrapped parser succeeds, this returns its value.
 * If the wrapped parser fails, this returns `undefined` without consuming input.
+* @template M The execution mode of the parser.
 * @template TValue The type of the value returned by the wrapped parser.
 * @template TState The type of the state used by the wrapped parser.
 * @param parser The {@link Parser} to make optional.
@@ -52,7 +72,25 @@ function parseOptionalStyle(context, parser) {
 *          or `undefined` if the wrapped parser fails to match.
 */
 function optional(parser) {
+	const syncParser = parser;
+	const isAsync = parser.$mode === "async";
+	function* suggestSync(context, prefix) {
+		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		yield* syncParser.suggest({
+			...context,
+			state: innerState
+		}, prefix);
+	}
+	async function* suggestAsync(context, prefix) {
+		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const suggestions = parser.suggest({
+			...context,
+			state: innerState
+		}, prefix);
+		for await (const s of suggestions) yield s;
+	}
 	return {
+		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -62,28 +100,27 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			return parseOptionalStyle(context, parser);
+			if (isAsync) return parseOptionalStyleAsync(context, parser);
+			return parseOptionalStyleSync(context, syncParser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") return {
 				success: true,
 				value: void 0
 			};
-			return parser.complete(state[0]);
+			if (!isAsync) return syncParser.complete(state[0]);
+			return (async () => await parser.complete(state[0]))();
 		},
 		suggest(context, prefix) {
-			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
-			return parser.suggest({
-				...context,
-				state: innerState
-			}, prefix);
+			if (isAsync) return suggestAsync(context, prefix);
+			return suggestSync(context, prefix);
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
 				state: state.state[0]
 			};
-			return parser.getDocFragments(innerState, defaultValue);
+			return syncParser.getDocFragments(innerState, defaultValue);
 		}
 	};
 }
@@ -122,7 +159,25 @@ var WithDefaultError = class extends Error {
 	}
 };
 function withDefault(parser, defaultValue, options) {
+	const syncParser = parser;
+	const isAsync = parser.$mode === "async";
+	function* suggestSync(context, prefix) {
+		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		yield* syncParser.suggest({
+			...context,
+			state: innerState
+		}, prefix);
+	}
+	async function* suggestAsync(context, prefix) {
+		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const suggestions = parser.suggest({
+			...context,
+			state: innerState
+		}, prefix);
+		for await (const s of suggestions) yield s;
+	}
 	return {
+		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -132,7 +187,8 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			return parseOptionalStyle(context, parser);
+			if (isAsync) return parseOptionalStyleAsync(context, parser);
+			return parseOptionalStyleSync(context, syncParser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") try {
@@ -147,14 +203,12 @@ function withDefault(parser, defaultValue, options) {
 					error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
 				};
 			}
-			return parser.complete(state[0]);
+			if (!isAsync) return syncParser.complete(state[0]);
+			return (async () => await parser.complete(state[0]))();
 		},
 		suggest(context, prefix) {
-			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
-			return parser.suggest({
-				...context,
-				state: innerState
-			}, prefix);
+			if (isAsync) return suggestAsync(context, prefix);
+			return suggestSync(context, prefix);
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -162,7 +216,7 @@ function withDefault(parser, defaultValue, options) {
 				state: state.state[0]
 			};
 			const actualDefaultValue = upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue;
-			const fragments = parser.getDocFragments(innerState, actualDefaultValue);
+			const fragments = syncParser.getDocFragments(innerState, actualDefaultValue);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -191,6 +245,7 @@ function withDefault(parser, defaultValue, options) {
 * - Computing derived values from parsed input
 * - Creating reusable transformations that can be applied to any parser
 *
+* @template M The execution mode of the parser.
 * @template T The type of the value produced by the original parser.
 * @template U The type of the value produced by the mapping function.
 * @template TState The type of the state used by the original parser.
@@ -214,33 +269,68 @@ function withDefault(parser, defaultValue, options) {
 * ```
 */
 function map(parser, transform) {
-	return {
+	const syncParser = parser;
+	const isAsync = parser.$mode === "async";
+	function* suggestSync(context, prefix) {
+		yield* syncParser.suggest(context, prefix);
+	}
+	async function* suggestAsync(context, prefix) {
+		const suggestions = parser.suggest(context, prefix);
+		for await (const s of suggestions) yield s;
+	}
+	const result = {
+		$mode: "sync",
 		$valueType: [],
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
 		initialState: parser.initialState,
-		parse: parser.parse.bind(parser),
+		parse(context) {
+			if (isAsync) return parser.parse(context);
+			return syncParser.parse(context);
+		},
 		complete(state) {
-			const result = parser.complete(state);
-			if (result.success) return {
-				success: true,
-				value: transform(result.value)
-			};
-			return result;
+			if (!isAsync) {
+				const innerResult = syncParser.complete(state);
+				if (innerResult.success) return {
+					success: true,
+					value: transform(innerResult.value)
+				};
+				return {
+					success: false,
+					error: innerResult.error
+				};
+			}
+			return (async () => {
+				const innerResult = await parser.complete(state);
+				if (innerResult.success) return {
+					success: true,
+					value: transform(innerResult.value)
+				};
+				return {
+					success: false,
+					error: innerResult.error
+				};
+			})();
 		},
 		suggest(context, prefix) {
-			return parser.suggest(context, prefix);
+			if (isAsync) return suggestAsync(context, prefix);
+			return suggestSync(context, prefix);
 		},
 		getDocFragments(state, _defaultValue) {
-			return parser.getDocFragments(state, void 0);
+			return syncParser.getDocFragments(state, void 0);
 		}
 	};
+	return {
+		...result,
+		$mode: parser.$mode
+	};
 }
 /**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
 * such as multiple command-line arguments or options.
+* @template M The execution mode of the parser.
 * @template TValue The type of the value that the parser produces.
 * @template TState The type of the state used by the parser.
 * @param parser The {@link Parser} to apply multiple times.
@@ -252,8 +342,59 @@ function map(parser, transform) {
 *          of type {@link TState}.
 */
 function multiple(parser, options = {}) {
+	const syncParser = parser;
+	const isAsync = parser.$mode === "async";
 	const { min = 0, max = Infinity } = options;
-	return {
+	const parseSync = (context) => {
+		let added = context.state.length < 1;
+		let result = syncParser.parse({
+			...context,
+			state: context.state.at(-1) ?? syncParser.initialState
+		});
+		if (!result.success) if (!added) {
+			result = syncParser.parse({
+				...context,
+				state: syncParser.initialState
+			});
+			if (!result.success) return result;
+			added = true;
+		} else return result;
+		return {
+			success: true,
+			next: {
+				...result.next,
+				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+			},
+			consumed: result.consumed
+		};
+	};
+	const parseAsync = async (context) => {
+		let added = context.state.length < 1;
+		let resultOrPromise = parser.parse({
+			...context,
+			state: context.state.at(-1) ?? parser.initialState
+		});
+		let result = await resultOrPromise;
+		if (!result.success) if (!added) {
+			resultOrPromise = parser.parse({
+				...context,
+				state: parser.initialState
+			});
+			result = await resultOrPromise;
+			if (!result.success) return result;
+			added = true;
+		} else return result;
+		return {
+			success: true,
+			next: {
+				...result.next,
+				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+			},
+			consumed: result.consumed
+		};
+	};
+	const resultParser = {
+		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -264,71 +405,79 @@ function multiple(parser, options = {}) {
 		}],
 		initialState: [],
 		parse(context) {
-			let added = context.state.length < 1;
-			let result = parser.parse({
-				...context,
-				state: context.state.at(-1) ?? parser.initialState
-			});
-			if (!result.success) if (!added) {
-				result = parser.parse({
-					...context,
-					state: parser.initialState
-				});
-				if (!result.success) return result;
-				added = true;
-			} else return result;
-			return {
-				success: true,
-				next: {
-					...result.next,
-					state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
-				},
-				consumed: result.consumed
-			};
+			if (isAsync) return parseAsync(context);
+			return parseSync(context);
 		},
 		complete(state) {
-			const result = [];
-			for (const s of state) {
-				const valueResult = parser.complete(s);
-				if (valueResult.success) result.push(valueResult.value);
-				else return {
-					success: false,
-					error: valueResult.error
-				};
-			}
-			if (result.length < min) {
-				const customMessage = options.errors?.tooFew;
-				return {
-					success: false,
-					error: customMessage ? typeof customMessage === "function" ? customMessage(min, result.length) : customMessage : message`Expected at least ${text(min.toLocaleString("en"))} values, but got only ${text(result.length.toLocaleString("en"))}.`
-				};
-			} else if (result.length > max) {
-				const customMessage = options.errors?.tooMany;
-				return {
-					success: false,
-					error: customMessage ? typeof customMessage === "function" ? customMessage(max, result.length) : customMessage : message`Expected at most ${text(max.toLocaleString("en"))} values, but got ${text(result.length.toLocaleString("en"))}.`
-				};
+			if (!isAsync) {
+				const result = [];
+				for (const s of state) {
+					const valueResult = syncParser.complete(s);
+					if (valueResult.success) result.push(valueResult.value);
+					else return {
+						success: false,
+						error: valueResult.error
+					};
+				}
+				return validateMultipleResult(result);
 			}
-			return {
-				success: true,
-				value: result
-			};
+			return (async () => {
+				const result = [];
+				for (const s of state) {
+					const valueResult = await parser.complete(s);
+					if (valueResult.success) result.push(valueResult.value);
+					else return {
+						success: false,
+						error: valueResult.error
+					};
+				}
+				return validateMultipleResult(result);
+			})();
 		},
 		suggest(context, prefix) {
 			const innerState = context.state.length > 0 ? context.state.at(-1) : parser.initialState;
-			return parser.suggest({
-				...context,
-				state: innerState
-			}, prefix);
+			if (isAsync) return async function* () {
+				const suggestions = parser.suggest({
+					...context,
+					state: innerState
+				}, prefix);
+				for await (const s of suggestions) yield s;
+			}();
+			return function* () {
+				yield* syncParser.suggest({
+					...context,
+					state: innerState
+				}, prefix);
+			}();
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
 				kind: "available",
 				state: state.state.at(-1)
 			} : { kind: "unavailable" };
-			return parser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}
 	};
+	function validateMultipleResult(result) {
+		if (result.length < min) {
+			const customMessage = options.errors?.tooFew;
+			return {
+				success: false,
+				error: customMessage ? typeof customMessage === "function" ? customMessage(min, result.length) : customMessage : message`Expected at least ${text(min.toLocaleString("en"))} values, but got only ${text(result.length.toLocaleString("en"))}.`
+			};
+		} else if (result.length > max) {
+			const customMessage = options.errors?.tooMany;
+			return {
+				success: false,
+				error: customMessage ? typeof customMessage === "function" ? customMessage(max, result.length) : customMessage : message`Expected at most ${text(max.toLocaleString("en"))} values, but got ${text(result.length.toLocaleString("en"))}.`
+			};
+		}
+		return {
+			success: true,
+			value: result
+		};
+	}
+	return resultParser;
 }
 
 //#endregion

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,73 @@ 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.
 *
@@ -212,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;