@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/message.cjs

@@ -1,6 +1,45 @@
+const require_displaywidth = require('./displaywidth.cjs');
 
 //#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
@@ -29,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;
@@ -68,7 +107,7 @@ function optionName(name) {
 function optionNames(names) {
 	return {
 		type: "optionNames",
-		optionNames: names
+		optionNames: [...names]
 	};
 }
 /**
@@ -105,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]
 	};
 }
 /**
@@ -165,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
@@ -198,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
@@ -268,7 +324,7 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: match[0].length
+								width: require_displaywidth.getDisplayWidth(match[0])
 							};
 						}
 					}
@@ -285,7 +341,7 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: match[0].length
+								width: require_displaywidth.getDisplayWidth(match[0])
 							};
 						}
 					}
@@ -294,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: require_displaywidth.getDisplayWidth(name)
 				};
 			} else if (term.type === "optionNames") {
 				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
@@ -306,7 +362,7 @@ function formatMessage(msg, options = {}) {
 					};
 					yield {
 						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-						width: name.length
+						width: require_displaywidth.getDisplayWidth(name)
 					};
 					i++;
 				}
@@ -314,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: require_displaywidth.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: require_displaywidth.getDisplayWidth(value$1)
 				};
 			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
@@ -330,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: require_displaywidth.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: require_displaywidth.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: require_displaywidth.getDisplayWidth(cmd)
 				};
 			} else if (term.type === "lineBreak") {
 				yield {
@@ -358,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: require_displaywidth.getDisplayWidth(displayText)
 					};
 				} else yield {
 					text: displayText,
-					width: displayText.length
+					width: require_displaywidth.getDisplayWidth(displayText)
 				};
 			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
 		}
@@ -375,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;
 		}
@@ -386,6 +442,8 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
+exports.cloneMessage = cloneMessage;
+exports.cloneMessageTerm = cloneMessageTerm;
 exports.commandLine = commandLine;
 exports.envVar = envVar;
 exports.formatMessage = formatMessage;

package/dist/message.d.cts

@@ -151,6 +151,26 @@ type MessageTerm =
  * displayed to the user with specific formatting.
  */
 type Message = readonly MessageTerm[];
+/**
+ * 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
+ */
+declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
+/**
+ * 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
+ */
+declare function cloneMessage(msg: Message): Message;
 /**
  * Creates a structured message with template strings and values.
  *
@@ -213,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;
 /**
@@ -299,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
@@ -310,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.
  */
@@ -380,4 +420,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.d.ts

@@ -151,6 +151,26 @@ type MessageTerm =
  * displayed to the user with specific formatting.
  */
 type Message = readonly MessageTerm[];
+/**
+ * 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
+ */
+declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
+/**
+ * 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
+ */
+declare function cloneMessage(msg: Message): Message;
 /**
  * Creates a structured message with template strings and values.
  *
@@ -213,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;
 /**
@@ -299,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
@@ -310,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.
  */
@@ -380,4 +420,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };