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

package/dist/message.d.cts

@@ -210,6 +210,71 @@ declare function envVar(envVar: string): MessageTerm;
  * @since 0.6.0
  */
 declare function commandLine(commandLine: string): MessageTerm;
+/**
+ * Options for the {@link valueSet} function.
+ * @since 0.9.0
+ */
+interface ValueSetOptions {
+  /**
+   * The locale(s) to use for list formatting.  Can be a BCP 47 language tag
+   * string, an array of language tags, an `Intl.Locale` object, or an array
+   * of `Intl.Locale` objects.  If not specified, the system default locale
+   * is used.
+   */
+  readonly locale?: string | readonly string[] | Intl.Locale | readonly Intl.Locale[];
+  /**
+   * The type of list to format:
+   *
+   * - `"conjunction"`: "A, B, and C" (default)
+   * - `"disjunction"`: "A, B, or C"
+   * - `"unit"`: "A, B, C"
+   *
+   * @default `"conjunction"`
+   */
+  readonly type?: "conjunction" | "disjunction" | "unit";
+  /**
+   * The style of the list formatting:
+   *
+   * - `"long"`: "A, B, and C" (default)
+   * - `"short"`: "A, B, & C"
+   * - `"narrow"`: "A, B, C"
+   *
+   * @default `"long"`
+   */
+  readonly style?: "long" | "short" | "narrow";
+}
+/**
+ * Creates a {@link Message} for a formatted list of values using the
+ * `Intl.ListFormat` API.  This is useful for displaying choice lists
+ * in error messages with proper locale-aware formatting.
+ *
+ * Each value in the list becomes a separate value term, and the separators
+ * (commas, "and", "or", etc.) become text terms.  This allows each value
+ * to be styled independently while respecting the locale's list formatting
+ * conventions.
+ *
+ * @example
+ * ```typescript
+ * // English conjunction (default): "error", "warn", and "info"
+ * const msg1 = message`Expected one of ${valueSet(["error", "warn", "info"])}.`;
+ *
+ * // English disjunction: "error", "warn", or "info"
+ * const msg2 = message`Expected ${
+ *   valueSet(["error", "warn", "info"], { type: "disjunction" })
+ * }.`;
+ *
+ * // Korean disjunction: "error", "warn" 또는 "info"
+ * const msg3 = message`${
+ *   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
+ * } 중 하나여야 합니다.`;
+ * ```
+ *
+ * @param values The list of values to format.
+ * @param options Optional formatting options including locale and list type.
+ * @returns A {@link Message} with alternating value and text terms.
+ * @since 0.9.0
+ */
+declare function valueSet(values: readonly string[], options?: ValueSetOptions): Message;
 /**
  * Options for the {@link formatMessage} function.
  */
@@ -258,4 +323,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values };

package/dist/message.d.ts

@@ -210,6 +210,71 @@ declare function envVar(envVar: string): MessageTerm;
  * @since 0.6.0
  */
 declare function commandLine(commandLine: string): MessageTerm;
+/**
+ * Options for the {@link valueSet} function.
+ * @since 0.9.0
+ */
+interface ValueSetOptions {
+  /**
+   * The locale(s) to use for list formatting.  Can be a BCP 47 language tag
+   * string, an array of language tags, an `Intl.Locale` object, or an array
+   * of `Intl.Locale` objects.  If not specified, the system default locale
+   * is used.
+   */
+  readonly locale?: string | readonly string[] | Intl.Locale | readonly Intl.Locale[];
+  /**
+   * The type of list to format:
+   *
+   * - `"conjunction"`: "A, B, and C" (default)
+   * - `"disjunction"`: "A, B, or C"
+   * - `"unit"`: "A, B, C"
+   *
+   * @default `"conjunction"`
+   */
+  readonly type?: "conjunction" | "disjunction" | "unit";
+  /**
+   * The style of the list formatting:
+   *
+   * - `"long"`: "A, B, and C" (default)
+   * - `"short"`: "A, B, & C"
+   * - `"narrow"`: "A, B, C"
+   *
+   * @default `"long"`
+   */
+  readonly style?: "long" | "short" | "narrow";
+}
+/**
+ * Creates a {@link Message} for a formatted list of values using the
+ * `Intl.ListFormat` API.  This is useful for displaying choice lists
+ * in error messages with proper locale-aware formatting.
+ *
+ * Each value in the list becomes a separate value term, and the separators
+ * (commas, "and", "or", etc.) become text terms.  This allows each value
+ * to be styled independently while respecting the locale's list formatting
+ * conventions.
+ *
+ * @example
+ * ```typescript
+ * // English conjunction (default): "error", "warn", and "info"
+ * const msg1 = message`Expected one of ${valueSet(["error", "warn", "info"])}.`;
+ *
+ * // English disjunction: "error", "warn", or "info"
+ * const msg2 = message`Expected ${
+ *   valueSet(["error", "warn", "info"], { type: "disjunction" })
+ * }.`;
+ *
+ * // Korean disjunction: "error", "warn" 또는 "info"
+ * const msg3 = message`${
+ *   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
+ * } 중 하나여야 합니다.`;
+ * ```
+ *
+ * @param values The list of values to format.
+ * @param options Optional formatting options including locale and list type.
+ * @returns A {@link Message} with alternating value and text terms.
+ * @since 0.9.0
+ */
+declare function valueSet(values: readonly string[], options?: ValueSetOptions): Message;
 /**
  * Options for the {@link formatMessage} function.
  */
@@ -258,4 +323,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values };

package/dist/message.js

@@ -139,6 +139,55 @@ function commandLine(commandLine$1) {
 	};
 }
 /**
+* Creates a {@link Message} for a formatted list of values using the
+* `Intl.ListFormat` API.  This is useful for displaying choice lists
+* in error messages with proper locale-aware formatting.
+*
+* Each value in the list becomes a separate value term, and the separators
+* (commas, "and", "or", etc.) become text terms.  This allows each value
+* to be styled independently while respecting the locale's list formatting
+* conventions.
+*
+* @example
+* ```typescript
+* // English conjunction (default): "error", "warn", and "info"
+* const msg1 = message`Expected one of ${valueSet(["error", "warn", "info"])}.`;
+*
+* // English disjunction: "error", "warn", or "info"
+* const msg2 = message`Expected ${
+*   valueSet(["error", "warn", "info"], { type: "disjunction" })
+* }.`;
+*
+* // Korean disjunction: "error", "warn" 또는 "info"
+* const msg3 = message`${
+*   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
+* } 중 하나여야 합니다.`;
+* ```
+*
+* @param values The list of values to format.
+* @param options Optional formatting options including locale and list type.
+* @returns A {@link Message} with alternating value and text terms.
+* @since 0.9.0
+*/
+function valueSet(values$1, options) {
+	if (values$1.length === 0) return [];
+	const formatter = new Intl.ListFormat(options?.locale, {
+		type: options?.type,
+		style: options?.style
+	});
+	const parts = formatter.formatToParts(values$1);
+	const result = [];
+	for (const part of parts) if (part.type === "element") result.push({
+		type: "value",
+		value: part.value
+	});
+	else result.push({
+		type: "text",
+		text: part.value
+	});
+	return result;
+}
+/**
 * Formats a {@link Message} into a human-readable string for
 * the terminal.
 * @param msg The message to format, which is an array of
@@ -266,4 +315,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values };
+export { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values };

package/dist/modifiers.cjs

@@ -9,31 +9,12 @@ const require_message = require('./message.cjs');
 * - Returning success with undefined state when inner parser fails without consuming
 * @internal
 */
-function parseOptionalStyleSync(context, parser) {
+function parseOptionalStyle(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,
@@ -64,7 +45,6 @@ function processOptionalStyleResult(result, innerState, context) {
 * 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.
@@ -72,25 +52,7 @@ function processOptionalStyleResult(result, innerState, context) {
 *          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,
@@ -100,27 +62,28 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			if (isAsync) return parseOptionalStyleAsync(context, parser);
-			return parseOptionalStyleSync(context, syncParser);
+			return parseOptionalStyle(context, parser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") return {
 				success: true,
 				value: void 0
 			};
-			if (!isAsync) return syncParser.complete(state[0]);
-			return (async () => await parser.complete(state[0]))();
+			return parser.complete(state[0]);
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
 				state: state.state[0]
 			};
-			return syncParser.getDocFragments(innerState, defaultValue);
+			return parser.getDocFragments(innerState, defaultValue);
 		}
 	};
 }
@@ -159,25 +122,7 @@ 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,
@@ -187,8 +132,7 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			if (isAsync) return parseOptionalStyleAsync(context, parser);
-			return parseOptionalStyleSync(context, syncParser);
+			return parseOptionalStyle(context, parser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") try {
@@ -203,12 +147,14 @@ function withDefault(parser, defaultValue, options) {
 					error: error instanceof WithDefaultError ? error.errorMessage : require_message.message`${require_message.text(String(error))}`
 				};
 			}
-			if (!isAsync) return syncParser.complete(state[0]);
-			return (async () => await parser.complete(state[0]))();
+			return parser.complete(state[0]);
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -216,7 +162,7 @@ function withDefault(parser, defaultValue, options) {
 				state: state.state[0]
 			};
 			const actualDefaultValue = upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue;
-			const fragments = syncParser.getDocFragments(innerState, actualDefaultValue);
+			const fragments = parser.getDocFragments(innerState, actualDefaultValue);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -245,7 +191,6 @@ 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.
@@ -269,68 +214,33 @@ function withDefault(parser, defaultValue, options) {
 * ```
 */
 function map(parser, transform) {
-	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",
+	return {
 		$valueType: [],
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
 		initialState: parser.initialState,
-		parse(context) {
-			if (isAsync) return parser.parse(context);
-			return syncParser.parse(context);
-		},
+		parse: parser.parse.bind(parser),
 		complete(state) {
-			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
-				};
-			})();
+			const result = parser.complete(state);
+			if (result.success) return {
+				success: true,
+				value: transform(result.value)
+			};
+			return result;
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			return parser.suggest(context, prefix);
 		},
 		getDocFragments(state, _defaultValue) {
-			return syncParser.getDocFragments(state, void 0);
+			return parser.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.
@@ -342,59 +252,8 @@ 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;
-	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,
+	return {
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -405,79 +264,71 @@ function multiple(parser, options = {}) {
 		}],
 		initialState: [],
 		parse(context) {
-			if (isAsync) return parseAsync(context);
-			return parseSync(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
+			};
 		},
 		complete(state) {
-			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);
+			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
+				};
 			}
-			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);
-			})();
+			if (result.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, result.length) : customMessage : require_message.message`Expected at least ${require_message.text(min.toLocaleString("en"))} values, but got only ${require_message.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 : require_message.message`Expected at most ${require_message.text(max.toLocaleString("en"))} values, but got ${require_message.text(result.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: result
+			};
 		},
 		suggest(context, prefix) {
 			const innerState = context.state.length > 0 ? context.state.at(-1) : parser.initialState;
-			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);
-			}();
+			return parser.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 syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			return parser.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 : require_message.message`Expected at least ${require_message.text(min.toLocaleString("en"))} values, but got only ${require_message.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 : require_message.message`Expected at most ${require_message.text(max.toLocaleString("en"))} values, but got ${require_message.text(result.length.toLocaleString("en"))}.`
-			};
-		}
-		return {
-			success: true,
-			value: result
-		};
-	}
-	return resultParser;
 }
 
 //#endregion