@optique/core 1.0.0-dev.1555 → 1.0.0-dev.1561

package/dist/usage.cjs

@@ -239,6 +239,9 @@ function formatUsage(programName, usage, options = {}) {
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
 * 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
@@ -251,8 +254,8 @@ function formatUsage(programName, usage, options = {}) {
 *
 * @param usage The usage description to normalize.
 * @returns A normalized usage description with degenerate terms removed,
-*          nested exclusive terms flattened, and remaining terms sorted for
-*          optimal readability.
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
 	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
@@ -266,11 +269,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min

package/dist/usage.d.cts

@@ -379,6 +379,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
  * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
@@ -391,8 +394,8 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *
  * @param usage The usage description to normalize.
  * @returns A normalized usage description with degenerate terms removed,
- *          nested exclusive terms flattened, and remaining terms sorted for
- *          optimal readability.
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.d.ts

@@ -379,6 +379,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
  * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
@@ -391,8 +394,8 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *
  * @param usage The usage description to normalize.
  * @returns A normalized usage description with degenerate terms removed,
- *          nested exclusive terms flattened, and remaining terms sorted for
- *          optimal readability.
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.js

@@ -239,6 +239,9 @@ function formatUsage(programName, usage, options = {}) {
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
 * 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
@@ -251,8 +254,8 @@ function formatUsage(programName, usage, options = {}) {
 *
 * @param usage The usage description to normalize.
 * @returns A normalized usage description with degenerate terms removed,
-*          nested exclusive terms flattened, and remaining terms sorted for
-*          optimal readability.
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
 	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
@@ -266,11 +269,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1555+118c402b",
+  "version": "1.0.0-dev.1561+241c020e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",