@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/message.js

@@ -1,5 +1,45 @@
+import { getDisplayWidth } from "./displaywidth.js";
+
 //#region src/message.ts
 /**
+* Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+* primitive fields and are cloned via object spread.  The `url` variant
+* receives a new `URL` object (since `structuredClone` cannot handle `URL`
+* on Node.js), and array-valued fields (`optionNames`, `values`) are
+* shallow-copied.
+*
+* @param term The message term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessageTerm(term) {
+	switch (term.type) {
+		case "optionNames": return {
+			...term,
+			optionNames: [...term.optionNames]
+		};
+		case "values": return {
+			...term,
+			values: [...term.values]
+		};
+		case "url": return {
+			type: "url",
+			url: new URL(term.url.href)
+		};
+		default: return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Message} array and all of its terms.
+*
+* @param msg The message to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessage(msg) {
+	return msg.map(cloneMessageTerm);
+}
+/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
@@ -28,8 +68,8 @@ function message(message$1, ...values$1) {
 			type: "value",
 			value: value$1
 		});
-		else if (Array.isArray(value$1)) messageTerms.push(...value$1);
-		else if (typeof value$1 === "object" && value$1 != null && "type" in value$1) messageTerms.push(value$1);
+		else if (Array.isArray(value$1)) messageTerms.push(...cloneMessage(value$1));
+		else if (typeof value$1 === "object" && value$1 != null && "type" in value$1) messageTerms.push(cloneMessageTerm(value$1));
 		else throw new TypeError(`Invalid value type in message: ${typeof value$1}.`);
 	}
 	return messageTerms;
@@ -67,7 +107,7 @@ function optionName(name) {
 function optionNames(names) {
 	return {
 		type: "optionNames",
-		optionNames: names
+		optionNames: [...names]
 	};
 }
 /**
@@ -104,11 +144,13 @@ 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
+		values: [...values$1]
 	};
 }
 /**
@@ -164,7 +206,7 @@ function url(url$1) {
 	if (typeof url$1 === "string") {
 		if (!URL.canParse(url$1)) throw new RangeError(`Invalid URL: ${url$1}.`);
 		urlObj = new URL(url$1);
-	} else urlObj = url$1;
+	} else urlObj = new URL(url$1.href);
 	return {
 		type: "url",
 		url: urlObj
@@ -197,29 +239,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
@@ -267,7 +324,7 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: match[0].length
+								width: getDisplayWidth(match[0])
 							};
 						}
 					}
@@ -284,7 +341,7 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: match[0].length
+								width: getDisplayWidth(match[0])
 							};
 						}
 					}
@@ -293,7 +350,7 @@ function formatMessage(msg, options = {}) {
 				const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
 				yield {
 					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-					width: name.length
+					width: getDisplayWidth(name)
 				};
 			} else if (term.type === "optionNames") {
 				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
@@ -305,7 +362,7 @@ function formatMessage(msg, options = {}) {
 					};
 					yield {
 						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-						width: name.length
+						width: getDisplayWidth(name)
 					};
 					i++;
 				}
@@ -313,13 +370,13 @@ function formatMessage(msg, options = {}) {
 				const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
 				yield {
 					text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
-					width: metavar$1.length
+					width: getDisplayWidth(metavar$1)
 				};
 			} else if (term.type === "value") {
 				const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
 				yield {
 					text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
-					width: value$1.length
+					width: getDisplayWidth(value$1)
 				};
 			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
@@ -329,20 +386,20 @@ function formatMessage(msg, options = {}) {
 				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
 					text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
-					width: value$1.length
+					width: getDisplayWidth(value$1)
 				};
 			}
 			else if (term.type === "envVar") {
 				const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
 				yield {
 					text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
-					width: envVar$1.length
+					width: getDisplayWidth(envVar$1)
 				};
 			} else if (term.type === "commandLine") {
 				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
 				yield {
 					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-					width: cmd.length
+					width: getDisplayWidth(cmd)
 				};
 			} else if (term.type === "lineBreak") {
 				yield {
@@ -357,11 +414,11 @@ function formatMessage(msg, options = {}) {
 					const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
 					yield {
 						text: hyperlink,
-						width: displayText.length
+						width: getDisplayWidth(displayText)
 					};
 				} else yield {
 					text: displayText,
-					width: displayText.length
+					width: getDisplayWidth(displayText)
 				};
 			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
 		}
@@ -374,7 +431,7 @@ function formatMessage(msg, options = {}) {
 			totalWidth = 0;
 			continue;
 		}
-		if (options.maxWidth != null && totalWidth + width > options.maxWidth) {
+		if (options.maxWidth != null && totalWidth > 0 && totalWidth + width > options.maxWidth) {
 			output += "\n";
 			totalWidth = 0;
 		}
@@ -385,4 +442,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };