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

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;
@@ -190,6 +195,7 @@ exports.option = require_primitives.option;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = parse;
+exports.passThrough = require_primitives.passThrough;
 exports.suggest = suggest;
 exports.tuple = require_constructs.tuple;
 exports.withDefault = require_modifiers.withDefault;

package/dist/parser.d.cts

@@ -3,8 +3,8 @@ import { Usage } from "./usage.cjs";
 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, argument, command, constant, flag, option } 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 { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.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, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, 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

@@ -3,8 +3,8 @@ import { Usage } from "./usage.js";
 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, argument, command, constant, flag, option } 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 { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.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, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, 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,8 +1,8 @@
 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 } from "./primitives.js";
+import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.ts
 /**
@@ -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, 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/primitives.cjs

@@ -723,10 +723,176 @@ 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: require_message.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: require_message.message`Options terminated; cannot capture pass-through options.`
+			};
+			if (format === "equalsOnly") {
+				if (!equalsOptionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: require_message.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: require_message.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: require_message.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
 exports.argument = argument;
 exports.command = command;
 exports.constant = constant;
 exports.flag = flag;
-exports.option = option;
+exports.option = option;
+exports.passThrough = passThrough;

package/dist/primitives.d.cts

@@ -307,5 +307,82 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  */
 declare function command<T, TState>(name: string, parser: Parser<T, TState>, options?: CommandOptions): Parser<T, CommandState<TState>>;
+/**
+ * Format options for how {@link passThrough} captures options.
+ * @since 0.8.0
+ */
+type PassThroughFormat = "equalsOnly" | "nextToken" | "greedy";
+/**
+ * Options for the {@link passThrough} parser.
+ * @since 0.8.0
+ */
+interface PassThroughOptions {
+  /**
+   * How to capture option values:
+   *
+   * - `"equalsOnly"`: Only capture `--opt=val` format (default, safest).
+   *   Values with spaces (`--opt val`) are not captured.
+   *
+   * - `"nextToken"`: Capture `--opt` and its value as separate tokens
+   *   (`--opt val`). The next token is captured if it doesn't start with `-`.
+   *
+   * - `"greedy"`: Capture *all* remaining tokens from first unrecognized token.
+   *   This is useful for wrapper/proxy tools that pass everything through.
+   *
+   * @default `"equalsOnly"`
+   */
+  readonly format?: PassThroughFormat;
+  /**
+   * A description of what pass-through options are used for.
+   */
+  readonly description?: Message;
+}
+/**
+ * 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
+ */
+declare function passThrough(options?: PassThroughOptions): Parser<readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };

package/dist/primitives.d.ts

@@ -307,5 +307,82 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  */
 declare function command<T, TState>(name: string, parser: Parser<T, TState>, options?: CommandOptions): Parser<T, CommandState<TState>>;
+/**
+ * Format options for how {@link passThrough} captures options.
+ * @since 0.8.0
+ */
+type PassThroughFormat = "equalsOnly" | "nextToken" | "greedy";
+/**
+ * Options for the {@link passThrough} parser.
+ * @since 0.8.0
+ */
+interface PassThroughOptions {
+  /**
+   * How to capture option values:
+   *
+   * - `"equalsOnly"`: Only capture `--opt=val` format (default, safest).
+   *   Values with spaces (`--opt val`) are not captured.
+   *
+   * - `"nextToken"`: Capture `--opt` and its value as separate tokens
+   *   (`--opt val`). The next token is captured if it doesn't start with `-`.
+   *
+   * - `"greedy"`: Capture *all* remaining tokens from first unrecognized token.
+   *   This is useful for wrapper/proxy tools that pass everything through.
+   *
+   * @default `"equalsOnly"`
+   */
+  readonly format?: PassThroughFormat;
+  /**
+   * A description of what pass-through options are used for.
+   */
+  readonly description?: Message;
+}
+/**
+ * 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
+ */
+declare function passThrough(options?: PassThroughOptions): Parser<readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };