@optique/core 0.8.0-dev.165 → 0.8.0-dev.167

package/dist/modifiers.js

@@ -2,6 +2,45 @@ import { formatMessage, message, text } from "./message.js";
 
 //#region src/modifiers.ts
 /**
+* Internal helper for optional-style parsing logic shared by optional()
+* and withDefault(). Handles the common pattern of:
+* - Unwrapping optional state to inner parser state
+* - Detecting if inner parser actually matched (state changed or no consumption)
+* - Returning success with undefined state when inner parser fails without consuming
+* @internal
+*/
+function parseOptionalStyle(context, parser) {
+	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const result = parser.parse({
+		...context,
+		state: innerState
+	});
+	if (result.success) {
+		if (result.next.state !== innerState || result.consumed.length === 0) return {
+			success: true,
+			next: {
+				...result.next,
+				state: [result.next.state]
+			},
+			consumed: result.consumed
+		};
+		return {
+			success: true,
+			next: {
+				...result.next,
+				state: context.state
+			},
+			consumed: result.consumed
+		};
+	}
+	if (result.consumed === 0) return {
+		success: true,
+		next: context,
+		consumed: []
+	};
+	return result;
+}
+/**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
 * If the wrapped parser succeeds, this returns its value.
@@ -23,35 +62,7 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
-			const result = parser.parse({
-				...context,
-				state: innerState
-			});
-			if (result.success) {
-				if (result.next.state !== innerState || result.consumed.length === 0) return {
-					success: true,
-					next: {
-						...result.next,
-						state: [result.next.state]
-					},
-					consumed: result.consumed
-				};
-				return {
-					success: true,
-					next: {
-						...result.next,
-						state: context.state
-					},
-					consumed: result.consumed
-				};
-			}
-			if (result.consumed === 0) return {
-				success: true,
-				next: context,
-				consumed: []
-			};
-			return result;
+			return parseOptionalStyle(context, parser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") return {
@@ -121,35 +132,7 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
-			const result = parser.parse({
-				...context,
-				state: innerState
-			});
-			if (result.success) {
-				if (result.next.state !== innerState || result.consumed.length === 0) return {
-					success: true,
-					next: {
-						...result.next,
-						state: [result.next.state]
-					},
-					consumed: result.consumed
-				};
-				return {
-					success: true,
-					next: {
-						...result.next,
-						state: context.state
-					},
-					consumed: result.consumed
-				};
-			}
-			if (result.consumed === 0) return {
-				success: true,
-				next: context,
-				consumed: []
-			};
-			return result;
+			return parseOptionalStyle(context, parser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") try {

package/dist/parser.cjs

@@ -34,7 +34,7 @@ function parse(parser, args) {
 		};
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer[0] === previousBuffer[0]) return {
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
 			success: false,
 			error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
@@ -90,7 +90,7 @@ function suggest(parser, args) {
 		if (!result.success) return Array.from(parser.suggest(context, prefix));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer[0] === previousBuffer[0]) return [];
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
 	}
 	return Array.from(parser.suggest(context, prefix));
 }
@@ -154,14 +154,18 @@ function getDocPage(parser, args = []) {
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
 	let i = 0;
 	for (const arg of args) {
+		if (i >= usage.length) break;
 		const term = usage[i];
-		if (usage.length > i && 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);
-			break;
-		}
-		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++;
+		} else i++;
 	}
 	return {
 		usage,
@@ -172,6 +176,7 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
+exports.DuplicateOptionError = require_constructs.DuplicateOptionError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.argument = require_primitives.argument;
 exports.command = require_primitives.command;

package/dist/parser.d.cts

@@ -4,7 +4,7 @@ import { DocFragments, DocPage } from "./doc.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
-import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 
 //#region src/parser.d.ts
 
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };

package/dist/parser.d.ts

@@ -4,7 +4,7 @@ import { DocFragments, DocPage } from "./doc.js";
 import { ValueParserResult } from "./valueparser.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
-import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#region src/parser.d.ts
 
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };

package/dist/parser.js

@@ -1,6 +1,6 @@
 import { message } from "./message.js";
 import { normalizeUsage } from "./usage.js";
-import { concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 
@@ -34,7 +34,7 @@ function parse(parser, args) {
 		};
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer[0] === previousBuffer[0]) return {
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
 			success: false,
 			error: message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
@@ -90,7 +90,7 @@ function suggest(parser, args) {
 		if (!result.success) return Array.from(parser.suggest(context, prefix));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer[0] === previousBuffer[0]) return [];
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
 	}
 	return Array.from(parser.suggest(context, prefix));
 }
@@ -154,14 +154,18 @@ function getDocPage(parser, args = []) {
 	const usage = [...normalizeUsage(parser.usage)];
 	let i = 0;
 	for (const arg of args) {
+		if (i >= usage.length) break;
 		const term = usage[i];
-		if (usage.length > i && 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);
-			break;
-		}
-		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++;
+		} else i++;
 	}
 	return {
 		usage,
@@ -172,4 +176,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };
+export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };

package/dist/suggestion.cjs

@@ -179,8 +179,58 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 		...suggestionMsg
 	] : baseError;
 }
+/**
+* Creates a unique key for a suggestion to enable deduplication.
+*
+* For literal suggestions, the text itself is used as the key.
+* For file suggestions, a composite key is created from the type,
+* extensions, and pattern.
+*
+* @param suggestion The suggestion to create a key for
+* @returns A string key that uniquely identifies this suggestion
+* @internal
+*/
+function getSuggestionKey(suggestion) {
+	if (suggestion.kind === "literal") return suggestion.text;
+	return `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",") ?? ""}:${suggestion.pattern ?? ""}`;
+}
+/**
+* Removes duplicate suggestions from an array while preserving order.
+*
+* Suggestions are considered duplicates if they have the same key:
+* - Literal suggestions: same text
+* - File suggestions: same type, extensions, and pattern
+*
+* The first occurrence of each unique suggestion is kept.
+*
+* @param suggestions Array of suggestions that may contain duplicates
+* @returns A new array with duplicates removed, preserving order of first occurrences
+*
+* @example
+* ```typescript
+* const suggestions = [
+*   { kind: "literal", text: "--verbose" },
+*   { kind: "literal", text: "--help" },
+*   { kind: "literal", text: "--verbose" }, // duplicate
+* ];
+* deduplicateSuggestions(suggestions);
+* // returns [{ kind: "literal", text: "--verbose" }, { kind: "literal", text: "--help" }]
+* ```
+*
+* @since 0.9.0
+*/
+function deduplicateSuggestions(suggestions) {
+	const seen = /* @__PURE__ */ new Set();
+	return suggestions.filter((suggestion) => {
+		const key = getSuggestionKey(suggestion);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
 
 //#endregion
 exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
 exports.createErrorWithSuggestions = createErrorWithSuggestions;
+exports.deduplicateSuggestions = deduplicateSuggestions;
 exports.findSimilar = findSimilar;

package/dist/suggestion.js

@@ -179,6 +179,55 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 		...suggestionMsg
 	] : baseError;
 }
+/**
+* Creates a unique key for a suggestion to enable deduplication.
+*
+* For literal suggestions, the text itself is used as the key.
+* For file suggestions, a composite key is created from the type,
+* extensions, and pattern.
+*
+* @param suggestion The suggestion to create a key for
+* @returns A string key that uniquely identifies this suggestion
+* @internal
+*/
+function getSuggestionKey(suggestion) {
+	if (suggestion.kind === "literal") return suggestion.text;
+	return `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",") ?? ""}:${suggestion.pattern ?? ""}`;
+}
+/**
+* Removes duplicate suggestions from an array while preserving order.
+*
+* Suggestions are considered duplicates if they have the same key:
+* - Literal suggestions: same text
+* - File suggestions: same type, extensions, and pattern
+*
+* The first occurrence of each unique suggestion is kept.
+*
+* @param suggestions Array of suggestions that may contain duplicates
+* @returns A new array with duplicates removed, preserving order of first occurrences
+*
+* @example
+* ```typescript
+* const suggestions = [
+*   { kind: "literal", text: "--verbose" },
+*   { kind: "literal", text: "--help" },
+*   { kind: "literal", text: "--verbose" }, // duplicate
+* ];
+* deduplicateSuggestions(suggestions);
+* // returns [{ kind: "literal", text: "--verbose" }, { kind: "literal", text: "--help" }]
+* ```
+*
+* @since 0.9.0
+*/
+function deduplicateSuggestions(suggestions) {
+	const seen = /* @__PURE__ */ new Set();
+	return suggestions.filter((suggestion) => {
+		const key = getSuggestionKey(suggestion);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
 
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, deduplicateSuggestions, findSimilar };

package/dist/valueparser.cjs

@@ -153,7 +153,7 @@ function integer(options) {
 	return {
 		metavar: options?.metavar ?? "INTEGER",
 		parse(input) {
-			if (!input.match(/^\d+$/)) return {
+			if (!input.match(/^-?\d+$/)) return {
 				success: false,
 				error: options?.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : require_message.message`Expected a valid integer, but got ${input}.`
 			};

package/dist/valueparser.js

@@ -153,7 +153,7 @@ function integer(options) {
 	return {
 		metavar: options?.metavar ?? "INTEGER",
 		parse(input) {
-			if (!input.match(/^\d+$/)) return {
+			if (!input.match(/^-?\d+$/)) return {
 				success: false,
 				error: options?.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : message`Expected a valid integer, but got ${input}.`
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.8.0-dev.165+f4b6fb65",
+  "version": "0.8.0-dev.167+f07435b4",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",