@optique/core 1.0.0-dev.1236 → 1.0.0-dev.1242

package/dist/doc.cjs

@@ -79,9 +79,42 @@ function formatDocPage(programName, page, options = {}) {
 	if (options.maxWidth != null) {
 		const hasEntries = page.sections.some((s) => s.entries.length > 0);
 		const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
-		const minWidth = needsDescColumn ? termIndent + 4 : hasEntries ? termIndent + 1 : 1;
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && e.default != null || options.showChoices && e.choices != null));
+		let minDescWidth = 1;
+		if (needsDescColumn) {
+			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => e.default != null))) {
+				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const hasEmptyDefault = page.sections.some((s) => s.entries.some((e) => e.default != null && Array.isArray(e.default) && e.default.length === 0));
+				minDescWidth = Math.max(minDescWidth, hasEmptyDefault ? prefix.length + suffix.length : prefix.length);
+			}
+			if (options.showChoices && page.sections.some((s) => s.entries.some((e) => e.choices != null))) {
+				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
+				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
+				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				const hasEmptyChoices = page.sections.some((s) => s.entries.some((e) => e.choices != null && Array.isArray(e.choices) && e.choices.length === 0));
+				minDescWidth = Math.max(minDescWidth, hasEmptyChoices ? prefix.length + label.length + suffix.length : prefix.length + label.length);
+			}
+		}
+		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
+		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
+		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
+		const usageMin = page.usage != null ? 8 + programName.length : 1;
+		let sectionMin = 1;
+		if (page.examples != null) sectionMin = Math.max(sectionMin, 9);
+		if (page.author != null) sectionMin = Math.max(sectionMin, 7);
+		if (page.bugs != null) sectionMin = Math.max(sectionMin, 5);
+		const minWidth = Math.max(entryMin, usageMin, sectionMin);
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+		if (needsDescColumn && minDescWidth > 1) {
+			const avail = options.maxWidth - termIndent - 2;
+			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
+			const descW = avail - effTW;
+			if (descW < minDescWidth) {
+				const needed = termIndent + termWidth + 2 + minDescWidth;
+				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+			}
+		}
 	}
 	let effectiveTermWidth;
 	if (options.maxWidth == null) effectiveTermWidth = termWidth;

package/dist/doc.js

@@ -79,9 +79,42 @@ function formatDocPage(programName, page, options = {}) {
 	if (options.maxWidth != null) {
 		const hasEntries = page.sections.some((s) => s.entries.length > 0);
 		const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
-		const minWidth = needsDescColumn ? termIndent + 4 : hasEntries ? termIndent + 1 : 1;
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && e.default != null || options.showChoices && e.choices != null));
+		let minDescWidth = 1;
+		if (needsDescColumn) {
+			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => e.default != null))) {
+				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const hasEmptyDefault = page.sections.some((s) => s.entries.some((e) => e.default != null && Array.isArray(e.default) && e.default.length === 0));
+				minDescWidth = Math.max(minDescWidth, hasEmptyDefault ? prefix.length + suffix.length : prefix.length);
+			}
+			if (options.showChoices && page.sections.some((s) => s.entries.some((e) => e.choices != null))) {
+				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
+				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
+				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				const hasEmptyChoices = page.sections.some((s) => s.entries.some((e) => e.choices != null && Array.isArray(e.choices) && e.choices.length === 0));
+				minDescWidth = Math.max(minDescWidth, hasEmptyChoices ? prefix.length + label.length + suffix.length : prefix.length + label.length);
+			}
+		}
+		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
+		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
+		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
+		const usageMin = page.usage != null ? 8 + programName.length : 1;
+		let sectionMin = 1;
+		if (page.examples != null) sectionMin = Math.max(sectionMin, 9);
+		if (page.author != null) sectionMin = Math.max(sectionMin, 7);
+		if (page.bugs != null) sectionMin = Math.max(sectionMin, 5);
+		const minWidth = Math.max(entryMin, usageMin, sectionMin);
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+		if (needsDescColumn && minDescWidth > 1) {
+			const avail = options.maxWidth - termIndent - 2;
+			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
+			const descW = avail - effTW;
+			if (descW < minDescWidth) {
+				const needed = termIndent + termWidth + 2 + minDescWidth;
+				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+			}
+		}
 	}
 	let effectiveTermWidth;
 	if (options.maxWidth == null) effectiveTermWidth = termWidth;

package/dist/valueparser.cjs

@@ -810,6 +810,10 @@ function locale(options = {}) {
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
+* @throws {TypeError} If any element of
+*   {@link UuidOptions.allowedVersions} is not an integer.
+* @throws {RangeError} If any element of
+*   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -817,7 +821,15 @@ function uuid(options = {}) {
 	require_nonempty.ensureNonEmptyString(metavar);
 	checkBooleanOption(options, "strict");
 	const strict = options.strict !== false;
-	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
+	const allowedVersions = options.allowedVersions != null ? (() => {
+		const unique = /* @__PURE__ */ new Set();
+		for (const v of options.allowedVersions) {
+			if (!Number.isInteger(v)) throw new TypeError(`Expected every element of allowedVersions to be an integer, but got value "${typeof v === "symbol" ? v.toString() : String(v)}" of type "${Array.isArray(v) ? "array" : v === null ? "null" : typeof v}".`);
+			if (v < 1 || v > 8) throw new RangeError(`Expected every element of allowedVersions to be between 1 and 8, but got: ${v}.`);
+			unique.add(v);
+		}
+		return Object.freeze([...unique]);
+	})() : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
 	const invalidVariant = options.errors?.invalidVariant;

package/dist/valueparser.d.cts

@@ -562,9 +562,13 @@ interface UuidOptions {
   readonly metavar?: NonEmptyString;
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
+   * Each version must be an integer between 1 and 8 (the standardized
+   * [RFC 9562] versions).  Duplicate entries are automatically removed.
    * If specified, the parser will validate that the UUID matches one of the
    * allowed versions.  If not specified, the accepted versions depend on
    * the {@link strict} option.
+   *
+   * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
    */
   readonly allowedVersions?: readonly number[];
   /**
@@ -633,6 +637,10 @@ interface UuidOptions {
  * @param options Configuration options for the UUID parser.
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.
+ * @throws {TypeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is not an integer.
+ * @throws {RangeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
  */
 declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
 /**

package/dist/valueparser.d.ts

@@ -562,9 +562,13 @@ interface UuidOptions {
   readonly metavar?: NonEmptyString;
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
+   * Each version must be an integer between 1 and 8 (the standardized
+   * [RFC 9562] versions).  Duplicate entries are automatically removed.
    * If specified, the parser will validate that the UUID matches one of the
    * allowed versions.  If not specified, the accepted versions depend on
    * the {@link strict} option.
+   *
+   * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
    */
   readonly allowedVersions?: readonly number[];
   /**
@@ -633,6 +637,10 @@ interface UuidOptions {
  * @param options Configuration options for the UUID parser.
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.
+ * @throws {TypeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is not an integer.
+ * @throws {RangeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
  */
 declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
 /**

package/dist/valueparser.js

@@ -810,6 +810,10 @@ function locale(options = {}) {
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
+* @throws {TypeError} If any element of
+*   {@link UuidOptions.allowedVersions} is not an integer.
+* @throws {RangeError} If any element of
+*   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -817,7 +821,15 @@ function uuid(options = {}) {
 	ensureNonEmptyString(metavar);
 	checkBooleanOption(options, "strict");
 	const strict = options.strict !== false;
-	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
+	const allowedVersions = options.allowedVersions != null ? (() => {
+		const unique = /* @__PURE__ */ new Set();
+		for (const v of options.allowedVersions) {
+			if (!Number.isInteger(v)) throw new TypeError(`Expected every element of allowedVersions to be an integer, but got value "${typeof v === "symbol" ? v.toString() : String(v)}" of type "${Array.isArray(v) ? "array" : v === null ? "null" : typeof v}".`);
+			if (v < 1 || v > 8) throw new RangeError(`Expected every element of allowedVersions to be between 1 and 8, but got: ${v}.`);
+			unique.add(v);
+		}
+		return Object.freeze([...unique]);
+	})() : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
 	const invalidVariant = options.errors?.invalidVariant;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1236+3ee9891d",
+  "version": "1.0.0-dev.1242+dd1a7a84",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",