@optique/core 1.0.0-dev.1572 → 1.0.0-dev.1574

package/dist/message.cjs

@@ -143,8 +143,10 @@ function value(value$1) {
 *               string representations of consecutive values.
 *               For example, `["42", "hello"]`.
 * @returns A {@link MessageTerm} representing the list of values.
+* @throws {TypeError} If the values array is empty.
 */
 function values(values$1) {
+	if (values$1.length === 0) throw new TypeError("values must not be empty.");
 	return {
 		type: "values",
 		values: [...values$1]
@@ -236,29 +238,44 @@ function link(href) {
 * to be styled independently while respecting the locale's list formatting
 * conventions.
 *
+* A fallback must be provided for when the values array is empty.  This can
+* be either a simple string (shorthand) or an options object with a
+* `fallback` field.  When the values array is empty, the fallback text
+* is returned as a single text term.  An empty fallback string produces
+* an empty {@link Message}.
+*
 * @example
 * ```typescript
 * // English conjunction (default): "error", "warn", and "info"
-* const msg1 = message`Expected one of ${valueSet(["error", "warn", "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" })
+*   valueSet(["error", "warn", "info"], { fallback: "", type: "disjunction" })
 * }.`;
 *
-* // Korean disjunction: "error", "warn" 또는 "info"
-* const msg3 = message`${
-*   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
-* } 중 하나여야 합니다.`;
+* // Fallback for empty list:
+* const msg3 = message`Expected one of ${valueSet([], "(none)")}.`;
+* // → "Expected one of (none)."
 * ```
 *
 * @param values The list of values to format.
-* @param options Optional formatting options including locale and list type.
+* @param fallbackOrOptions A fallback string for empty lists, or an options
+*                          object including the fallback and formatting
+*                          options such as locale and list type.
 * @returns A {@link Message} with alternating value and text terms.
+* @throws {TypeError} If the fallback parameter is missing or invalid.
 * @since 0.9.0
 */
-function valueSet(values$1, options) {
-	if (values$1.length === 0) return [];
+function valueSet(values$1, fallbackOrOptions) {
+	if (fallbackOrOptions == null || typeof fallbackOrOptions !== "string" && typeof fallbackOrOptions.fallback !== "string") throw new TypeError("valueSet() requires a fallback string or an options object with a fallback field.");
+	const options = typeof fallbackOrOptions === "string" ? { fallback: fallbackOrOptions } : fallbackOrOptions;
+	if (values$1.length === 0) return options.fallback === "" ? [] : [{
+		type: "text",
+		text: options.fallback
+	}];
 	const formatter = new Intl.ListFormat(options?.locale, {
 		type: options?.type,
 		style: options?.style

package/dist/message.d.cts

@@ -233,6 +233,7 @@ declare function value(value: string): MessageTerm;
  *               string representations of consecutive values.
  *               For example, `["42", "hello"]`.
  * @returns A {@link MessageTerm} representing the list of values.
+ * @throws {TypeError} If the values array is empty.
  */
 declare function values(values: readonly string[]): MessageTerm;
 /**
@@ -319,6 +320,15 @@ interface ValueSetOptions {
    * @default `"long"`
    */
   readonly style?: "long" | "short" | "narrow";
+  /**
+   * A fallback text to return when the values array is empty.  When provided
+   * and the values array is empty, a {@link Message} containing a single text
+   * term with this string is returned instead of an empty {@link Message}.
+   * An empty string produces an empty {@link Message}.
+   *
+   * @since 1.0.0
+   */
+  readonly fallback: string;
 }
 /**
  * Creates a {@link Message} for a formatted list of values using the
@@ -330,28 +340,38 @@ interface ValueSetOptions {
  * to be styled independently while respecting the locale's list formatting
  * conventions.
  *
+ * A fallback must be provided for when the values array is empty.  This can
+ * be either a simple string (shorthand) or an options object with a
+ * `fallback` field.  When the values array is empty, the fallback text
+ * is returned as a single text term.  An empty fallback string produces
+ * an empty {@link Message}.
+ *
  * @example
  * ```typescript
  * // English conjunction (default): "error", "warn", and "info"
- * const msg1 = message`Expected one of ${valueSet(["error", "warn", "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" })
+ *   valueSet(["error", "warn", "info"], { fallback: "", type: "disjunction" })
  * }.`;
  *
- * // Korean disjunction: "error", "warn" 또는 "info"
- * const msg3 = message`${
- *   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
- * } 중 하나여야 합니다.`;
+ * // Fallback for empty list:
+ * const msg3 = message`Expected one of ${valueSet([], "(none)")}.`;
+ * // → "Expected one of (none)."
  * ```
  *
  * @param values The list of values to format.
- * @param options Optional formatting options including locale and list type.
+ * @param fallbackOrOptions A fallback string for empty lists, or an options
+ *                          object including the fallback and formatting
+ *                          options such as locale and list type.
  * @returns A {@link Message} with alternating value and text terms.
+ * @throws {TypeError} If the fallback parameter is missing or invalid.
  * @since 0.9.0
  */
-declare function valueSet(values: readonly string[], options?: ValueSetOptions): Message;
+declare function valueSet(values: readonly string[], fallbackOrOptions: string | ValueSetOptions): Message;
 /**
  * Options for the {@link formatMessage} function.
  */

package/dist/message.d.ts

@@ -233,6 +233,7 @@ declare function value(value: string): MessageTerm;
  *               string representations of consecutive values.
  *               For example, `["42", "hello"]`.
  * @returns A {@link MessageTerm} representing the list of values.
+ * @throws {TypeError} If the values array is empty.
  */
 declare function values(values: readonly string[]): MessageTerm;
 /**
@@ -319,6 +320,15 @@ interface ValueSetOptions {
    * @default `"long"`
    */
   readonly style?: "long" | "short" | "narrow";
+  /**
+   * A fallback text to return when the values array is empty.  When provided
+   * and the values array is empty, a {@link Message} containing a single text
+   * term with this string is returned instead of an empty {@link Message}.
+   * An empty string produces an empty {@link Message}.
+   *
+   * @since 1.0.0
+   */
+  readonly fallback: string;
 }
 /**
  * Creates a {@link Message} for a formatted list of values using the
@@ -330,28 +340,38 @@ interface ValueSetOptions {
  * to be styled independently while respecting the locale's list formatting
  * conventions.
  *
+ * A fallback must be provided for when the values array is empty.  This can
+ * be either a simple string (shorthand) or an options object with a
+ * `fallback` field.  When the values array is empty, the fallback text
+ * is returned as a single text term.  An empty fallback string produces
+ * an empty {@link Message}.
+ *
  * @example
  * ```typescript
  * // English conjunction (default): "error", "warn", and "info"
- * const msg1 = message`Expected one of ${valueSet(["error", "warn", "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" })
+ *   valueSet(["error", "warn", "info"], { fallback: "", type: "disjunction" })
  * }.`;
  *
- * // Korean disjunction: "error", "warn" 또는 "info"
- * const msg3 = message`${
- *   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
- * } 중 하나여야 합니다.`;
+ * // Fallback for empty list:
+ * const msg3 = message`Expected one of ${valueSet([], "(none)")}.`;
+ * // → "Expected one of (none)."
  * ```
  *
  * @param values The list of values to format.
- * @param options Optional formatting options including locale and list type.
+ * @param fallbackOrOptions A fallback string for empty lists, or an options
+ *                          object including the fallback and formatting
+ *                          options such as locale and list type.
  * @returns A {@link Message} with alternating value and text terms.
+ * @throws {TypeError} If the fallback parameter is missing or invalid.
  * @since 0.9.0
  */
-declare function valueSet(values: readonly string[], options?: ValueSetOptions): Message;
+declare function valueSet(values: readonly string[], fallbackOrOptions: string | ValueSetOptions): Message;
 /**
  * Options for the {@link formatMessage} function.
  */

package/dist/message.js

@@ -142,8 +142,10 @@ function value(value$1) {
 *               string representations of consecutive values.
 *               For example, `["42", "hello"]`.
 * @returns A {@link MessageTerm} representing the list of values.
+* @throws {TypeError} If the values array is empty.
 */
 function values(values$1) {
+	if (values$1.length === 0) throw new TypeError("values must not be empty.");
 	return {
 		type: "values",
 		values: [...values$1]
@@ -235,29 +237,44 @@ function link(href) {
 * to be styled independently while respecting the locale's list formatting
 * conventions.
 *
+* A fallback must be provided for when the values array is empty.  This can
+* be either a simple string (shorthand) or an options object with a
+* `fallback` field.  When the values array is empty, the fallback text
+* is returned as a single text term.  An empty fallback string produces
+* an empty {@link Message}.
+*
 * @example
 * ```typescript
 * // English conjunction (default): "error", "warn", and "info"
-* const msg1 = message`Expected one of ${valueSet(["error", "warn", "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" })
+*   valueSet(["error", "warn", "info"], { fallback: "", type: "disjunction" })
 * }.`;
 *
-* // Korean disjunction: "error", "warn" 또는 "info"
-* const msg3 = message`${
-*   valueSet(["error", "warn", "info"], { locale: "ko", type: "disjunction" })
-* } 중 하나여야 합니다.`;
+* // Fallback for empty list:
+* const msg3 = message`Expected one of ${valueSet([], "(none)")}.`;
+* // → "Expected one of (none)."
 * ```
 *
 * @param values The list of values to format.
-* @param options Optional formatting options including locale and list type.
+* @param fallbackOrOptions A fallback string for empty lists, or an options
+*                          object including the fallback and formatting
+*                          options such as locale and list type.
 * @returns A {@link Message} with alternating value and text terms.
+* @throws {TypeError} If the fallback parameter is missing or invalid.
 * @since 0.9.0
 */
-function valueSet(values$1, options) {
-	if (values$1.length === 0) return [];
+function valueSet(values$1, fallbackOrOptions) {
+	if (fallbackOrOptions == null || typeof fallbackOrOptions !== "string" && typeof fallbackOrOptions.fallback !== "string") throw new TypeError("valueSet() requires a fallback string or an options object with a fallback field.");
+	const options = typeof fallbackOrOptions === "string" ? { fallback: fallbackOrOptions } : fallbackOrOptions;
+	if (values$1.length === 0) return options.fallback === "" ? [] : [{
+		type: "text",
+		text: options.fallback
+	}];
 	const formatter = new Intl.ListFormat(options?.locale, {
 		type: options?.type,
 		style: options?.style

package/dist/primitives.cjs

@@ -543,7 +543,10 @@ function option(...args) {
 				fragments: [],
 				description: options.description
 			};
-			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
+			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
+				fallback: "",
+				type: "unit"
+			}) : void 0;
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -915,7 +918,10 @@ function argument(valueParser, options = {}) {
 				fragments: [],
 				description: options.description
 			};
-			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
+			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
+				fallback: "",
+				type: "unit"
+			}) : void 0;
 			const fragments = [{
 				type: "entry",
 				term,

package/dist/primitives.js

@@ -543,7 +543,10 @@ function option(...args) {
 				fragments: [],
 				description: options.description
 			};
-			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
+			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
+				fallback: "",
+				type: "unit"
+			}) : void 0;
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -915,7 +918,10 @@ function argument(valueParser, options = {}) {
 				fragments: [],
 				description: options.description
 			};
-			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
+			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
+				fallback: "",
+				type: "unit"
+			}) : void 0;
 			const fragments = [{
 				type: "entry",
 				term,

package/dist/valueparser.cjs

@@ -271,7 +271,10 @@ function formatNumberChoiceError(input, validChoices, allChoices, invalidChoice)
 function formatDefaultChoiceError(input, choices) {
 	const choiceStrings = choices.filter((c) => typeof c === "string" || !Number.isNaN(c)).map((c) => Object.is(c, -0) ? "-0" : String(c));
 	if (choiceStrings.length === 0 && choices.length > 0) return require_message.message`No valid choices are configured, but got ${input}.`;
-	return require_message.message`Expected one of ${require_message.valueSet(choiceStrings, { locale: "en-US" })}, but got ${input}.`;
+	return require_message.message`Expected one of ${require_message.valueSet(choiceStrings, {
+		fallback: "",
+		locale: "en-US"
+	})}, but got ${input}.`;
 }
 /**
 * Creates a {@link ValueParser} for strings.
@@ -576,7 +579,10 @@ function url(options = {}) {
 						type: "text",
 						text: " is not allowed. Allowed protocols: "
 					},
-					...require_message.valueSet(originalProtocols, { locale: "en-US" }),
+					...require_message.valueSet(originalProtocols, {
+						fallback: "",
+						locale: "en-US"
+					}),
 					{
 						type: "text",
 						text: "."
@@ -1534,7 +1540,10 @@ function email(options) {
 									type: "text",
 									text: " is not allowed. Allowed domains: "
 								},
-								...require_message.valueSet(allowedDomains, { locale: "en-US" }),
+								...require_message.valueSet(allowedDomains, {
+									fallback: "",
+									locale: "en-US"
+								}),
 								{
 									type: "text",
 									text: "."
@@ -1585,7 +1594,10 @@ function email(options) {
 								type: "text",
 								text: " is not allowed. Allowed domains: "
 							},
-							...require_message.valueSet(allowedDomains, { locale: "en-US" }),
+							...require_message.valueSet(allowedDomains, {
+								fallback: "",
+								locale: "en-US"
+							}),
 							{
 								type: "text",
 								text: "."
@@ -2519,7 +2531,10 @@ function domain(options) {
 							type: "text",
 							text: " is not allowed. Allowed TLDs: "
 						},
-						...require_message.valueSet(allowedTlds, { locale: "en-US" }),
+						...require_message.valueSet(allowedTlds, {
+							fallback: "",
+							locale: "en-US"
+						}),
 						{
 							type: "text",
 							text: "."

package/dist/valueparser.js

@@ -271,7 +271,10 @@ function formatNumberChoiceError(input, validChoices, allChoices, invalidChoice)
 function formatDefaultChoiceError(input, choices) {
 	const choiceStrings = choices.filter((c) => typeof c === "string" || !Number.isNaN(c)).map((c) => Object.is(c, -0) ? "-0" : String(c));
 	if (choiceStrings.length === 0 && choices.length > 0) return message`No valid choices are configured, but got ${input}.`;
-	return message`Expected one of ${valueSet(choiceStrings, { locale: "en-US" })}, but got ${input}.`;
+	return message`Expected one of ${valueSet(choiceStrings, {
+		fallback: "",
+		locale: "en-US"
+	})}, but got ${input}.`;
 }
 /**
 * Creates a {@link ValueParser} for strings.
@@ -576,7 +579,10 @@ function url(options = {}) {
 						type: "text",
 						text: " is not allowed. Allowed protocols: "
 					},
-					...valueSet(originalProtocols, { locale: "en-US" }),
+					...valueSet(originalProtocols, {
+						fallback: "",
+						locale: "en-US"
+					}),
 					{
 						type: "text",
 						text: "."
@@ -1534,7 +1540,10 @@ function email(options) {
 									type: "text",
 									text: " is not allowed. Allowed domains: "
 								},
-								...valueSet(allowedDomains, { locale: "en-US" }),
+								...valueSet(allowedDomains, {
+									fallback: "",
+									locale: "en-US"
+								}),
 								{
 									type: "text",
 									text: "."
@@ -1585,7 +1594,10 @@ function email(options) {
 								type: "text",
 								text: " is not allowed. Allowed domains: "
 							},
-							...valueSet(allowedDomains, { locale: "en-US" }),
+							...valueSet(allowedDomains, {
+								fallback: "",
+								locale: "en-US"
+							}),
 							{
 								type: "text",
 								text: "."
@@ -2519,7 +2531,10 @@ function domain(options) {
 							type: "text",
 							text: " is not allowed. Allowed TLDs: "
 						},
-						...valueSet(allowedTlds, { locale: "en-US" }),
+						...valueSet(allowedTlds, {
+							fallback: "",
+							locale: "en-US"
+						}),
 						{
 							type: "text",
 							text: "."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1572+6945a5ef",
+  "version": "1.0.0-dev.1574+d9b3596d",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",