@optique/core 0.8.4 → 0.8.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2025 Hong Minhee
+Copyright 2025–2026 Hong Minhee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/dist/constructs.cjs

@@ -73,7 +73,8 @@ function analyzeNoMatchContext(parsers) {
 */
 var DuplicateOptionError = class extends Error {
 	constructor(optionName$1, sources) {
-		super(`Duplicate option name "${optionName$1}" found in fields: ${sources.join(", ")}. Each option name must be unique within a parser combinator.`);
+		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
+		super(`Duplicate option name "${optionName$1}" found in fields: ${sourceNames.join(", ")}. Each option name must be unique within a parser combinator.`);
 		this.optionName = optionName$1;
 		this.sources = sources;
 		this.name = "DuplicateOptionError";
@@ -367,17 +368,35 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		parsers = labelOrParsers;
 		options = maybeParsersOrOptions ?? {};
 	}
-	const parserPairs = Object.entries(parsers);
+	const parserKeys = Reflect.ownKeys(parsers);
+	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	const initialState = {};
+	for (const key of parserKeys) initialState[key] = parsers[key].initialState;
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
-	const noMatchContext = analyzeNoMatchContext(Object.values(parsers));
+	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	return {
 		$valueType: [],
 		$stateType: [],
-		priority: Math.max(...Object.values(parsers).map((p) => p.priority)),
+		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: parserPairs.flatMap(([_, p]) => p.usage),
-		initialState: Object.fromEntries(Object.entries(parsers).map(([key, parser]) => [key, parser.initialState])),
+		initialState,
 		parse(context) {
+			if (!options.allowDuplicates) {
+				const optionNameSources = /* @__PURE__ */ new Map();
+				for (const [field, parser] of parserPairs) {
+					const names = require_usage.extractOptionNames(parser.usage);
+					for (const name of names) {
+						if (!optionNameSources.has(name)) optionNameSources.set(name, []);
+						optionNameSources.get(name).push(field);
+					}
+				}
+				for (const [name, sources] of optionNameSources) if (sources.length > 1) return {
+					success: false,
+					consumed: 0,
+					error: require_message.message`Duplicate option name ${require_message.optionName(name)} found in fields: ${require_message.values(sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s))}. Each option name must be unique within a parser combinator.`
+				};
+			}
 			let error = {
 				consumed: 0,
 				error: context.buffer.length > 0 ? (() => {
@@ -447,8 +466,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		},
 		complete(state) {
 			const result = {};
-			for (const field in state) {
-				if (!(field in parsers)) continue;
+			for (const field of parserKeys) {
 				const valueResult = parsers[field].complete(state[field]);
 				if (valueResult.success) result[field] = valueResult.value;
 				else return {
@@ -760,8 +778,16 @@ function merge(...args) {
 			return require_suggestion.deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(state, _defaultValue) {
-			const fragments = parsers.flatMap((p) => {
-				const parserState = p.initialState === void 0 ? { kind: "unavailable" } : state.kind === "unavailable" ? { kind: "unavailable" } : {
+			const fragments = parsers.flatMap((p, i) => {
+				let parserState;
+				if (p.initialState === void 0) {
+					const key = `__parser_${i}`;
+					if (state.kind === "available" && state.state && typeof state.state === "object" && key in state.state) parserState = {
+						kind: "available",
+						state: state.state[key]
+					};
+					else parserState = { kind: "unavailable" };
+				} else parserState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state
 				};

package/dist/constructs.d.cts

@@ -83,8 +83,8 @@ interface OrErrorOptions {
  */
 declare class DuplicateOptionError extends Error {
   readonly optionName: string;
-  readonly sources: string[];
-  constructor(optionName: string, sources: string[]);
+  readonly sources: readonly (string | symbol)[];
+  constructor(optionName: string, sources: readonly (string | symbol)[]);
 }
 /**
  * Creates a parser that combines two mutually exclusive parsers into one.

package/dist/constructs.d.ts

@@ -83,8 +83,8 @@ interface OrErrorOptions {
  */
 declare class DuplicateOptionError extends Error {
   readonly optionName: string;
-  readonly sources: string[];
-  constructor(optionName: string, sources: string[]);
+  readonly sources: readonly (string | symbol)[];
+  constructor(optionName: string, sources: readonly (string | symbol)[]);
 }
 /**
  * Creates a parser that combines two mutually exclusive parsers into one.

package/dist/constructs.js

@@ -73,7 +73,8 @@ function analyzeNoMatchContext(parsers) {
 */
 var DuplicateOptionError = class extends Error {
 	constructor(optionName$1, sources) {
-		super(`Duplicate option name "${optionName$1}" found in fields: ${sources.join(", ")}. Each option name must be unique within a parser combinator.`);
+		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
+		super(`Duplicate option name "${optionName$1}" found in fields: ${sourceNames.join(", ")}. Each option name must be unique within a parser combinator.`);
 		this.optionName = optionName$1;
 		this.sources = sources;
 		this.name = "DuplicateOptionError";
@@ -367,17 +368,35 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		parsers = labelOrParsers;
 		options = maybeParsersOrOptions ?? {};
 	}
-	const parserPairs = Object.entries(parsers);
+	const parserKeys = Reflect.ownKeys(parsers);
+	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	const initialState = {};
+	for (const key of parserKeys) initialState[key] = parsers[key].initialState;
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
-	const noMatchContext = analyzeNoMatchContext(Object.values(parsers));
+	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	return {
 		$valueType: [],
 		$stateType: [],
-		priority: Math.max(...Object.values(parsers).map((p) => p.priority)),
+		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: parserPairs.flatMap(([_, p]) => p.usage),
-		initialState: Object.fromEntries(Object.entries(parsers).map(([key, parser]) => [key, parser.initialState])),
+		initialState,
 		parse(context) {
+			if (!options.allowDuplicates) {
+				const optionNameSources = /* @__PURE__ */ new Map();
+				for (const [field, parser] of parserPairs) {
+					const names = extractOptionNames(parser.usage);
+					for (const name of names) {
+						if (!optionNameSources.has(name)) optionNameSources.set(name, []);
+						optionNameSources.get(name).push(field);
+					}
+				}
+				for (const [name, sources] of optionNameSources) if (sources.length > 1) return {
+					success: false,
+					consumed: 0,
+					error: message`Duplicate option name ${optionName(name)} found in fields: ${values(sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s))}. Each option name must be unique within a parser combinator.`
+				};
+			}
 			let error = {
 				consumed: 0,
 				error: context.buffer.length > 0 ? (() => {
@@ -447,8 +466,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		},
 		complete(state) {
 			const result = {};
-			for (const field in state) {
-				if (!(field in parsers)) continue;
+			for (const field of parserKeys) {
 				const valueResult = parsers[field].complete(state[field]);
 				if (valueResult.success) result[field] = valueResult.value;
 				else return {
@@ -760,8 +778,16 @@ function merge(...args) {
 			return deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(state, _defaultValue) {
-			const fragments = parsers.flatMap((p) => {
-				const parserState = p.initialState === void 0 ? { kind: "unavailable" } : state.kind === "unavailable" ? { kind: "unavailable" } : {
+			const fragments = parsers.flatMap((p, i) => {
+				let parserState;
+				if (p.initialState === void 0) {
+					const key = `__parser_${i}`;
+					if (state.kind === "available" && state.state && typeof state.state === "object" && key in state.state) parserState = {
+						kind: "available",
+						state: state.state[key]
+					};
+					else parserState = { kind: "unavailable" };
+				} else parserState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state
 				};

package/dist/parser.cjs

@@ -95,6 +95,26 @@ function suggest(parser, args) {
 	return Array.from(parser.suggest(context, prefix));
 }
 /**
+* Recursively searches for a command within nested exclusive usage terms.
+* When the command is found, returns the expanded usage terms for that command.
+*
+* @param term The usage term to search in
+* @param commandName The command name to find
+* @returns The expanded usage terms if found, null otherwise
+*/
+function findCommandInExclusive(term, commandName) {
+	if (term.type !== "exclusive") return null;
+	for (const termGroup of term.terms) {
+		const firstTerm = termGroup[0];
+		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
+		if (firstTerm?.type === "exclusive") {
+			const found = findCommandInExclusive(firstTerm, commandName);
+			if (found) return [...found, ...termGroup.slice(1)];
+		}
+	}
+	return null;
+}
+/**
 * Generates a documentation page for a parser based on its current state after
 * attempting to parse the provided arguments. This function is useful for
 * creating help documentation that reflects the current parsing context.
@@ -157,14 +177,11 @@ function getDocPage(parser, args = []) {
 		if (i >= usage.length) break;
 		const term = usage[i];
 		if (term.type === "exclusive") {
-			for (const termGroup of term.terms) {
-				const firstTerm = termGroup[0];
-				if (firstTerm?.type !== "command" || firstTerm.name !== arg) continue;
-				usage.splice(i, 1, ...termGroup);
-				i += termGroup.length;
-				break;
-			}
-			if (usage[i] === term) i++;
+			const found = findCommandInExclusive(term, arg);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				i += found.length;
+			} else i++;
 		} else i++;
 	}
 	return {

package/dist/parser.js

@@ -95,6 +95,26 @@ function suggest(parser, args) {
 	return Array.from(parser.suggest(context, prefix));
 }
 /**
+* Recursively searches for a command within nested exclusive usage terms.
+* When the command is found, returns the expanded usage terms for that command.
+*
+* @param term The usage term to search in
+* @param commandName The command name to find
+* @returns The expanded usage terms if found, null otherwise
+*/
+function findCommandInExclusive(term, commandName) {
+	if (term.type !== "exclusive") return null;
+	for (const termGroup of term.terms) {
+		const firstTerm = termGroup[0];
+		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
+		if (firstTerm?.type === "exclusive") {
+			const found = findCommandInExclusive(firstTerm, commandName);
+			if (found) return [...found, ...termGroup.slice(1)];
+		}
+	}
+	return null;
+}
+/**
 * Generates a documentation page for a parser based on its current state after
 * attempting to parse the provided arguments. This function is useful for
 * creating help documentation that reflects the current parsing context.
@@ -157,14 +177,11 @@ function getDocPage(parser, args = []) {
 		if (i >= usage.length) break;
 		const term = usage[i];
 		if (term.type === "exclusive") {
-			for (const termGroup of term.terms) {
-				const firstTerm = termGroup[0];
-				if (firstTerm?.type !== "command" || firstTerm.name !== arg) continue;
-				usage.splice(i, 1, ...termGroup);
-				i += termGroup.length;
-				break;
-			}
-			if (usage[i] === term) i++;
+			const found = findCommandInExclusive(term, arg);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				i += found.length;
+			} else i++;
 		} else i++;
 	}
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",