@optique/core 0.8.0-dev.164 → 0.8.0-dev.166

package/dist/primitives.js

@@ -723,6 +723,171 @@ function command(name, parser, options = {}) {
 		}
 	};
 }
+/**
+* Creates a parser that collects unrecognized options and passes them through.
+* This is useful for building wrapper CLI tools that need to forward unknown
+* options to an underlying tool.
+*
+* **Important**: This parser intentionally weakens Optique's strict parsing
+* philosophy where "all input must be recognized." The benefit is enabling
+* legitimate wrapper/proxy tool patterns, but the trade-off is that typos
+* in pass-through options won't be caught.
+*
+* @param options Configuration for how to capture options.
+* @returns A {@link Parser} that captures unrecognized options as an array
+*          of strings.
+*
+* @example
+* ```typescript
+* // Default format: only captures --opt=val
+* const parser = object({
+*   debug: option("--debug"),
+*   extra: passThrough(),
+* });
+*
+* // mycli --debug --foo=bar --baz=qux
+* // → { debug: true, extra: ["--foo=bar", "--baz=qux"] }
+*
+* // nextToken format: captures --opt val pairs
+* const parser = object({
+*   debug: option("--debug"),
+*   extra: passThrough({ format: "nextToken" }),
+* });
+*
+* // mycli --debug --foo bar
+* // → { debug: true, extra: ["--foo", "bar"] }
+*
+* // greedy format: captures all remaining tokens
+* const parser = command("exec", object({
+*   container: argument(string()),
+*   args: passThrough({ format: "greedy" }),
+* }));
+*
+* // myproxy exec mycontainer --verbose -it bash
+* // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+* ```
+*
+* @since 0.8.0
+*/
+function passThrough(options = {}) {
+	const format = options.format ?? "equalsOnly";
+	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
+	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: -10,
+		usage: [{ type: "passthrough" }],
+		initialState: [],
+		parse(context) {
+			if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: message`No input to pass through.`
+			};
+			const token = context.buffer[0];
+			if (format === "greedy") {
+				const captured = [...context.buffer];
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: [],
+						state: [...context.state, ...captured]
+					},
+					consumed: captured
+				};
+			}
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: message`Options terminated; cannot capture pass-through options.`
+			};
+			if (format === "equalsOnly") {
+				if (!equalsOptionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: message`Expected --option=value format, but got: ${token}.`
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+			}
+			if (format === "nextToken") {
+				if (!optionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: message`Expected option, but got: ${token}.`
+				};
+				if (token.includes("=")) return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+				const nextToken = context.buffer[1];
+				if (nextToken !== void 0 && !optionPattern.test(nextToken)) return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(2),
+						state: [
+							...context.state,
+							token,
+							nextToken
+						]
+					},
+					consumed: [token, nextToken]
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: message`Unknown passThrough format: ${format}.`
+			};
+		},
+		complete(state) {
+			return {
+				success: true,
+				value: state
+			};
+		},
+		suggest(_context, _prefix) {
+			return [];
+		},
+		getDocFragments(_state, _defaultValue) {
+			return {
+				fragments: [{
+					type: "entry",
+					term: { type: "passthrough" },
+					description: options.description
+				}],
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `passThrough(${format})`;
+		}
+	};
+}
 
 //#endregion
-export { argument, command, constant, flag, option };
+export { argument, command, constant, flag, option, passThrough };

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/usage.cjs

@@ -331,7 +331,13 @@ function* formatUsageTermInternal(term, options) {
 		text: term.value,
 		width: term.value.length
 	};
-	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+	else if (term.type === "passthrough") {
+		const text = "[...]";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 5
+		};
+	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

package/dist/usage.d.cts

@@ -123,6 +123,16 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+}
+/**
+ * A pass-through term, which represents unrecognized options that are
+ * collected and passed through to an underlying tool or command.
+ * @since 0.8.0
+ */ | {
+  /**
+   * The type of the term, which is always `"passthrough"` for this term.
+   */
+  readonly type: "passthrough";
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.d.ts

@@ -123,6 +123,16 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+}
+/**
+ * A pass-through term, which represents unrecognized options that are
+ * collected and passed through to an underlying tool or command.
+ * @since 0.8.0
+ */ | {
+  /**
+   * The type of the term, which is always `"passthrough"` for this term.
+   */
+  readonly type: "passthrough";
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.js

@@ -330,7 +330,13 @@ function* formatUsageTermInternal(term, options) {
 		text: term.value,
 		width: term.value.length
 	};
-	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+	else if (term.type === "passthrough") {
+		const text = "[...]";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 5
+		};
+	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

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.164+250237ef",
+  "version": "0.8.0-dev.166+141d0c79",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",