--- description: >- Construct combinators compose multiple parsers into complex structures using object(), tuple(), seq(), or(), and merge() to build sophisticated CLI interfaces with full type inference. --- Construct combinators ===================== Construct combinators are the high-level combinators that compose multiple parsers into complex, structured CLI interfaces. While primitive parsers handle individual options and arguments, construct combinators orchestrate them into cohesive applications with sophisticated behavior patterns like mutually exclusive commands, structured configuration, and modular option groups. Understanding construct combinators is essential for building real-world CLI applications. They provide the architectural patterns you need to create maintainable, user-friendly interfaces that can grow in complexity without becoming unwieldy. Each construct combinator follows Optique's compositional philosophy: complex behavior emerges from combining simple, well-understood pieces. The power of construct combinators lies in their ability to preserve full type safety while enabling complex composition. TypeScript automatically infers the result types of even deeply nested parser structures, ensuring that your parsed CLI data is fully typed without manual type annotations. `object()` parser ----------------- The `object()` parser combines multiple named parsers into a single parser that produces a structured object. This is the primary way to group related options and arguments into logical units, creating the foundation for most CLI applications. ~~~~ typescript twoslash import { object } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { argument, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; const serverConfig = object({ name: argument(string({ metavar: "NAME" })), port: option("-p", "--port", integer({ min: 1, max: 0xffff })), host: option("-h", "--host", string()), verbose: option("-v", "--verbose") }); type ServerConfig = InferValue; // ^? // Type automatically inferred as above. ~~~~ > [!TIP] > `object()` matches its fields by parser priority, not declaration order. > If one parser must consume input before another becomes active, use > [`seq()`](#seq-parser). For example, a wrapper command can require a program > name before forwarding the remaining arguments with `passThrough()`. ### Labeled objects You can provide a label for documentation and error reporting purposes. This label appears in help text to group related options: ~~~~ typescript twoslash import { object } from "@optique/core/constructs"; import { optional } from "@optique/core/modifiers"; import { option } from "@optique/core/primitives"; import { choice, integer, string } from "@optique/core/valueparser"; // ---cut-before--- const networkOptions = object("Network Configuration", { host: option("--host", string()), port: option("--port", integer()), ssl: option("--ssl") }); const loggingOptions = object("Logging Options", { logLevel: option("--log-level", choice(["debug", "info", "warn", "error"])), logFile: optional(option("--log-file", string())) }); ~~~~ ### Parser priority The `object()` parser uses the highest priority among its constituent parsers. This ensures that higher-priority parsers (like commands) within the object are tried before lower-priority parsers in other parts of the CLI structure. `tuple()` parser ---------------- The `tuple()` parser combines multiple parsers into a sequential parser that produces a tuple (ordered heterogenous array) of results. Unlike `object()` which uses named fields, `tuple()` preserves the order and positional nature of its components. ~~~~ typescript twoslash import { tuple } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { argument, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; const connectionTuple = tuple([ option("--host", string()), option("--port", integer()), argument(string({ metavar: "DATABASE" })) ] as const); type Connection = InferValue; // ^? // Type automatically inferred as above. ~~~~ ### Sequential parsing The `tuple()` parser processes its component parsers in priority order (not array order), which means parsers with higher priority are tried first regardless of their position in the tuple: ~~~~ typescript twoslash import { tuple } from "@optique/core/constructs"; import { argument, command, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- // Even though argument is last in the array, it might be parsed first // depending on the current parsing context and available input const mixedTuple = tuple([ option("-v", "--verbose"), // Priority 10 command("start", argument(string())), // Priority 15 - tried first argument(string()) // Priority 5 ] as const); ~~~~ ### Labeled tuples Like `object()`, `tuple()` supports labels for documentation: ~~~~ typescript twoslash import { tuple } from "@optique/core/constructs"; import { optional } from "@optique/core/modifiers"; import type { InferValue } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { float, string } from "@optique/core/valueparser"; // ---cut-before--- const coordinates = tuple("Location", [ option("--lat", float({ metavar: "LATITUDE" })), option("--lon", float({ metavar: "LONGITUDE" })), optional(option("--alt", float({ metavar: "ALTITUDE" }))) ] as const); type Coordinate = InferValue; // ^? // Type automatically inferred as above. ~~~~ ### Usage patterns Tuples are useful when you need: - Ordered results where position matters - Integration with APIs that expect arrays - Processing of homogeneous but positionally significant data ~~~~ typescript twoslash import { tuple } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { argument } from "@optique/core/primitives"; import { integer } from "@optique/core/valueparser"; // ---cut-before--- const rangeParser = tuple([ argument(integer({ metavar: "START" })), argument(integer({ metavar: "END" })) ]); // Usage: myapp 10 20 // Result: [10, 20] const config = parse(rangeParser, ["10", "20"]); if (config.success) { const [start, end] = config.value; console.log(`Processing range ${start} to ${end}.`); } ~~~~ `seq()` parser -------------- The `seq()` parser combines multiple parsers into an ordered parser that produces a tuple of results. Unlike [`tuple()`](#tuple-parser), which lets child parsers compete by priority, `seq()` keeps a cursor and applies child parsers in declaration order. This is useful when the grammar itself is ordered, especially when an optional positional value appears before a later command: ~~~~ typescript twoslash import { object, or, seq } from "@optique/core/constructs"; import { optional } from "@optique/core/modifiers"; import type { InferValue } from "@optique/core/parser"; import { argument, command, constant, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; const parser = seq( optional(argument(string({ metavar: "PROFILE" }))), or( command( "build", object({ action: constant("build"), target: argument(string({ metavar: "TARGET" })), }), ), command( "deploy", object({ action: constant("deploy"), environment: argument(string({ metavar: "ENV" })), force: option("--force"), }), ), ), ); type Parsed = InferValue; // ^? // Type automatically inferred as above. ~~~~ With this parser, both of these forms are valid: ~~~~ bash tool build app tool staging deploy production --force ~~~~ The first command leaves the optional profile as `undefined`; the second command sets it to `"staging"`. When the current child parser can finish without consuming more input, `seq()` can advance to a later command name. ### Ordered usage output Because `seq()` preserves declaration order, generated usage follows the grammar you wrote instead of priority order: ~~~~ typescript twoslash import { object, or, seq } from "@optique/core/constructs"; import { formatUsage } from "@optique/core/usage"; import { argument, command, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- const copyParser = seq( argument(string({ metavar: "SOURCE" })), or(command("local", object({})), command("remote", object({}))), option("--force"), ); const usage = formatUsage("copy", copyParser.usage); // ^? // "copy SOURCE (local | remote) [--force]" ~~~~ ### Duplicate options `seq()` rejects duplicate option names only when the same option can be active at the same cursor position. Duplicate options separated by a required sequential boundary are allowed, but ambiguous duplicates can be enabled explicitly with `{ allowDuplicates: true }`. ### No backtracking `seq()` does not backtrack after a later parser succeeds. It can skip fixed optional parsers before a later command name, but ambiguous variadic positionals still need an explicit grammar boundary such as a command name, an option, or `--`. `or()` parser ------------- The `or()` parser creates mutually exclusive alternatives, trying each alternative in order until one succeeds. This is fundamental for building CLIs with different modes of operation, subcommands, or mutually exclusive option sets. > [!NOTE] > `or()` can use a definitive non-consuming branch as a fallback. For example, > `or(constant("fallback"), option("-o", string()))` succeeds on empty input > and still prefers the consuming branch when `-o` is present. Wrap the whole > parser with [`optional()`](./modifiers.md#optional-parser) when you want > “no selection” to produce `undefined` instead of an explicit fallback value. > [!IMPORTANT] > TypeScript overload inference for `or()` supports up to 15 parser > arguments. When you need 16 or more branches, split them into nested > groups so each `or()` call stays at 15 or fewer arguments. > > ~~~~ typescript twoslash > import { or } from "@optique/core/constructs"; > import { command, constant } from "@optique/core/primitives"; > // ---cut-before--- > const commandGroupA = or( > command("a1", constant("a1")), > command("a2", constant("a2")), > command("a3", constant("a3")), > command("a4", constant("a4")), > command("a5", constant("a5")), > command("a6", constant("a6")), > command("a7", constant("a7")), > command("a8", constant("a8")), > ); > > const commandGroupB = or( > command("b1", constant("b1")), > command("b2", constant("b2")), > command("b3", constant("b3")), > command("b4", constant("b4")), > command("b5", constant("b5")), > command("b6", constant("b6")), > command("b7", constant("b7")), > command("b8", constant("b8")), > ); > > const parser = or(commandGroupA, commandGroupB); > ~~~~ ~~~~ typescript twoslash import { object, or } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { command, constant, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; const parser = or( // Server mode object({ mode: constant("server"), port: option("-p", "--port", integer()), host: option("-h", "--host", string()) }), // Client mode object({ mode: constant("client"), connect: option("-c", "--connect", string()), timeout: option("-t", "--timeout", integer()) }) ); type Result = InferValue; // ^? // Type automatically inferred as discriminated union. ~~~~ ### Discriminated unions The `or()` parser creates TypeScript discriminated unions when used with `constant()` parsers. This enables type-safe pattern matching: ~~~~ typescript twoslash import { object, or } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { command, constant, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; const parser = or( // Server mode object({ mode: constant("server"), port: option("-p", "--port", integer()), host: option("-h", "--host", string()) }), // Client mode object({ mode: constant("client"), connect: option("-c", "--connect", string()), timeout: option("-t", "--timeout", integer()) }) ); // ---cut-before--- const config = parse(parser, ["-p", "8080", "-h", "localhost"]); if (config.success) { switch (config.value.mode) { case "server": // TypeScript knows this is server config console.log(`Server running on ${config.value.host}:${config.value.port}.`); break; case "client": // TypeScript knows this is client config console.log(`Connecting to ${config.value.connect} with timeout ${config.value.timeout}.`); break; } } ~~~~ ### Command alternatives The most common use of `or()` is for subcommand dispatch: ~~~~ typescript twoslash import { object, or } from "@optique/core/constructs"; import { multiple, optional, withDefault } from "@optique/core/modifiers"; import { argument, command, constant, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- const gitLike = or( command("add", object({ type: constant("add"), files: multiple(argument(string())), all: optional(option("-A", "--all")) })), command("commit", object({ type: constant("commit"), message: option("-m", "--message", string()), amend: optional(option("--amend")) })), command("push", object({ type: constant("push"), remote: withDefault(option("-r", "--remote", string()), "origin"), force: optional(option("-f", "--force")) })) ); // Usage examples: // myapp add file1.txt file2.txt --all // myapp commit -m "Fix parser bug" --amend // myapp push --remote upstream --force ~~~~ When a CLI needs flags that apply to every subcommand, combine `or()` with [`merge()`](#merge-parser) to lift those options out of each branch. See the [*Shared options across subcommands*](../cookbook.md#shared-options-across-subcommands) recipe for a worked example. ### Alternative parsing strategies You can also use `or()` for different parsing approaches of the same logical concept: ~~~~ typescript twoslash import { object, or } from "@optique/core/constructs"; import { constant, option } from "@optique/core/primitives"; import { integer, string, url } from "@optique/core/valueparser"; // ---cut-before--- const flexibleConfig = or( // Configuration via individual options object({ source: constant("options"), host: option("--host", string()), port: option("--port", integer()), ssl: option("--ssl") }), // Configuration via config file object({ source: constant("file"), configFile: option("-c", "--config", string()) }), // Configuration via URL object({ source: constant("url"), connectionString: option("--url", url()) }) ); ~~~~ ### Optional alternatives with `optional(or(...))` When you want to allow *none* of the alternatives to be provided, wrap the `or()` with [`optional()`](./modifiers.md#optional-parser). This is useful when you have mutually exclusive options that are all optional: ~~~~ typescript twoslash import { or } from "@optique/core/constructs"; import { map, optional } from "@optique/core/modifiers"; import { parse } from "@optique/core/parser"; import { flag } from "@optique/core/primitives"; // Without optional(): at least one flag MUST be provided const requiredChoice = or( map(flag("--verbose", "-v"), () => "verbose" as const), map(flag("--quiet", "-q"), () => "quiet" as const), ); // With optional(): none of the flags need to be provided const optionalChoice = optional( or( map(flag("--verbose", "-v"), () => "verbose" as const), map(flag("--quiet", "-q"), () => "quiet" as const), ), ); // No arguments: requiredChoice fails, optionalChoice succeeds const result1 = parse(requiredChoice, []); console.log(result1.success); // false - "No matching option found" const result2 = parse(optionalChoice, []); console.log(result2.success); // true if (result2.success) { console.log(result2.value); // undefined } // With --verbose: both succeed const result3 = parse(optionalChoice, ["--verbose"]); if (result3.success) { console.log(result3.value); // "verbose" } ~~~~ This pattern is common when implementing verbosity levels or output format selection where a default behavior should apply when no explicit choice is made. You can combine it with [`withDefault()`](./modifiers.md#withdefault-parser) to provide a fallback value instead of `undefined`: ~~~~ typescript twoslash import { or } from "@optique/core/constructs"; import { map, withDefault } from "@optique/core/modifiers"; import { flag } from "@optique/core/primitives"; // ---cut-before--- const verbosityLevel = withDefault( or( map(flag("--verbose", "-v"), () => "verbose" as const), map(flag("--quiet", "-q"), () => "quiet" as const), ), "normal" as const, // Default when neither flag is provided ); // No flags → "normal" // --verbose → "verbose" // --quiet → "quiet" ~~~~ ### Error message customization *This feature is available since Optique 0.9.0.* The `or()` parser generates contextual error messages by analyzing what types of inputs are expected (options, commands, or arguments). You can customize these messages using the `errors.noMatch` option, which supports both static messages and dynamic functions for advanced use cases like internationalization: Initial mismatch messages in `or()`, `longestMatch()`, `object()`, and related constructs are built when their failure is selected or its `error` property is read. Their error callbacks may still run in other paths, such as completion probes, so callback counts and invocation timing are not fixed. Use callbacks to format messages without side effects. ~~~~ typescript twoslash import { message, or } from "@optique/core"; import { command, constant } from "@optique/core/primitives"; // ---cut-before--- // Static custom error message const parser1 = or( command("add", constant("add")), command("remove", constant("remove")), { errors: { noMatch: message`Invalid command. Please use 'add' or 'remove'.` } } ); // Dynamic error message for internationalization const parser2 = or( command("add", constant("add")), command("remove", constant("remove")), { errors: { noMatch: ({ hasOptions, hasCommands, hasArguments }) => { if (hasCommands && !hasOptions && !hasArguments) { return message`일치하는 명령을 찾을 수 없습니다.`; // Korean } return message`잘못된 입력입니다.`; } } } ); ~~~~ The function form receives a `NoMatchContext` object with three boolean flags: - `hasOptions`: Whether any parsers expect options - `hasCommands`: Whether any parsers expect commands - `hasArguments`: Whether any parsers expect arguments This enables precise, context-aware error messages. For example, if all parsers expect only commands, you can show “No matching command found” instead of the generic “No matching option or command found.” **Default behavior** (when no custom error is provided): | Context | Default error message | | ------------------------------- | ------------------------------------------------- | | Only arguments expected | `Missing required argument.` | | Only commands expected | `No matching command found.` | | Only options expected | `No matching option found.` | | Commands and options expected | `No matching option or command found.` | | Arguments and options expected | `No matching option or argument found.` | | Arguments and commands expected | `No matching command or argument found.` | | All three types expected | `No matching option, command, or argument found.` | The default messages automatically adapt to your parser structure, but you can override them for custom formatting or localization needs. ### Zero-consumed fallback branches When all input has been consumed and no branch matched, `or()` can fall back to a branch that succeeds without consuming any input, such as `constant()`. A branch qualifies as a fallback candidate only when *all* of the following hold: - The result is not `provisional` (tentative zero-consumed matches from nested constructs like `conditional()` are excluded). - The branch has no `leadingNames` and does not accept arbitrary tokens—i.e., it can *never* match an input token. - Exactly one branch qualifies (ambiguous fallbacks are rejected). - No other branch consumed tokens before failing. - The input buffer is empty. In practice, this means: - Annotation-backed parsers like `bindEnv(option(...))` or `bindConfig(option(...))` are *not* eligible, because they inherit `leadingNames` from the inner option. - Positional parsers like `argument(...)` are *not* eligible either, because they accept arbitrary tokens even though they have no `leadingNames`. To provide a fallback value for an env/config-backed option, use the parser's own default mechanism instead of wrapping it in `or()`: ~~~~ typescript twoslash import { option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; declare function bindEnv(p: any, o: any): any; declare const envContext: any; // ---cut-before--- // Instead of or(bindEnv(option(...)), constant("fallback")): bindEnv(option("--mode", string()), { context: envContext, key: "APP_MODE", parser: string(), default: "fallback", // built-in fallback }) ~~~~ ### Fallback branches in usage output Usage output follows the same rule. When Optique can tell from the parsers themselves whether `or()` picks a branch for an empty argument list, help text and man page synopses draw the whole group as optional or required to match: ~~~~ typescript twoslash import { or } from "@optique/core/constructs"; import { optional } from "@optique/core/modifiers"; import { argument, constant, option } from "@optique/core/primitives"; import { formatUsage } from "@optique/core/usage"; import { string } from "@optique/core/valueparser"; // ---cut-before--- // Two branches succeed without input, so the choice is ambiguous and an // empty argument list fails: formatUsage("app", or( optional(argument(string({ metavar: "FILE" }))), optional(argument(string({ metavar: "DIR" }))), ).usage); // "app (FILE | DIR)" // constant() is the only fallback, so FILE may be omitted: formatUsage("app", or( constant("default"), argument(string({ metavar: "FILE" })), ).usage); // "app [FILE]" // The optional option has a leading name, so it is not a fallback: formatUsage("app", or( optional(option("--name", string())), argument(string({ metavar: "FILE" })), ).usage); // "app (--name STRING | FILE)" ~~~~ The same applies to `longestMatch()` and to `multiple()`, which is drawn as `FILE...` or `[FILE...]` depending on whether it can finish without input. A few cases keep the notation the parsers declare. Custom parsers without [declared empty-input behavior](./extend.md#declaring-empty-input-behavior) remain unknown. Parsers bound to an outside source, such as `bindEnv()` or `bindConfig()`, declare their known parse step but leave completion unknown when it depends on runtime data. An alternative made of several optional terms means “at least one of them,” which synopsis notation cannot say without listing combinations, so it stays as written. Hidden terms are left out of the judgment as well: a group whose only required parts are hidden looks the way its visible terms read. Each group is also judged on its own, so a group can read as optional even when an enclosing `object()` still needs input; see the `acceptsEmpty` field of `UsageTerm` for details. `merge()` parser ---------------- The `merge()` parser combines multiple object-generating parsers into a single unified parser, enabling modular CLI design through reusable option groups. While originally designed for `object()` parsers, it now accepts any parser that produces object-like values, including `withDefault()`, `map()`, and other transformative parsers. This is essential for building maintainable applications where related options can be shared across different commands or modes. A common composition is `merge(globals, or(...))`: define shared options as a standalone `object()` and merge them alongside the subcommand dispatcher. See [*Shared options across subcommands*](../cookbook.md#shared-options-across-subcommands) in the cookbook for a worked example. > [!IMPORTANT] > TypeScript overload inference for `merge()` supports up to 15 parser > arguments. Calls beyond 15 now fail at compile time with an actionable > message. For 16+ parsers, split into nested groups so each `merge()` call > stays at 15 or fewer arguments. ~~~~ typescript twoslash import { merge, object, or } from "@optique/core/constructs"; import { optional } from "@optique/core/modifiers"; import { constant, option } from "@optique/core/primitives"; import { string, integer, choice } from "@optique/core/valueparser"; // Define reusable option groups const networkOptions = object("Network", { host: option("--host", string()), port: option("--port", integer({ min: 1, max: 0xffff })) }); const authOptions = object("Authentication", { username: option("-u", "--user", string()), password: optional(option("-p", "--pass", string())), token: optional(option("-t", "--token", string())) }); const loggingOptions = object("Logging", { logLevel: option("--log-level", choice(["debug", "info", "warn", "error"])), logFile: optional(option("--log-file", string())) }); // Combine groups for different application modes const devMode = merge( object({ mode: constant("development") }), networkOptions, loggingOptions ); const prodMode = merge( object({ mode: constant("production") }), networkOptions, authOptions, loggingOptions, object("Production", { workers: option("-w", "--workers", integer({ min: 1 })), configFile: option("-c", "--config", string()) }) ); const applicationConfig = or(devMode, prodMode); ~~~~ ### Labeled merge groups *This feature is available since Optique 0.4.0.* Like `object()`, the `merge()` parser can accept an optional label as its first parameter. This label appears in help text to organize the combined options into a logical group, making documentation clearer when merging parsers that don't already have their own labels: ~~~~ typescript twoslash import { merge, object } from "@optique/core/constructs"; import { option } from "@optique/core/primitives"; import { string, integer, choice } from "@optique/core/valueparser"; // Define simple option groups without labels const connectionOptions = object({ host: option("--host", string()), port: option("--port", integer()) }); const performanceOptions = object({ workers: option("-w", "--workers", integer({ min: 1 })), timeout: option("-t", "--timeout", integer()), cache: option("--cache", choice(["none", "memory", "disk"])) }); // Combine with a label for organized help text const serverConfig = merge( "Server Configuration", // Label for the merged group connectionOptions, performanceOptions ); // The label "Server Configuration" will appear in help text, // grouping all options from both parsers under this section ~~~~ This is particularly useful when combining parsers from different modules or when the constituent parsers don't have their own labels. It ensures that the merged options appear as a cohesive group in help documentation rather than scattered individual options. ### Advanced parser combinations *This feature is available since Optique 0.3.0.* The `merge()` parser can now combine various types of object-generating parsers, not just `object()` parsers. This enables sophisticated patterns like dependent options and conditional configurations: ~~~~ typescript twoslash import { merge, object } from "@optique/core/constructs"; import { map, withDefault } from "@optique/core/modifiers"; import type { InferValue } from "@optique/core/parser"; import { flag, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; import { run } from "@optique/run"; // Dependent options pattern: options that are only available when a flag is set const dependentOptions = withDefault( object({ feature: flag("-f", "--feature"), config: option("-c", "--config", string()), level: option("-l", "--level", integer()) }), { feature: false as const } as const ); // Transform parser results const transformedConfig = map( object({ host: option("--host", string()), port: option("--port", integer()) }), ({ host, port }) => ({ endpoint: `${host}:${port}` }) ); // Combine different parser types const advancedParser = merge( dependentOptions, // withDefault() parser transformedConfig, // map() result object({ // traditional object() parser verbose: option("-v", "--verbose") }) ); type Result = InferValue; // ^? const result: Result = run(advancedParser); ~~~~ ### Dependent options pattern A common use case is creating options that are only relevant when certain conditions are met: ~~~~ typescript twoslash import { merge, object } from "@optique/core/constructs"; import { withDefault } from "@optique/core/modifiers"; import { flag, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; // ---cut-before--- const serverMode = withDefault( object({ server: flag("-s", "--server"), port: option("-p", "--port", integer()), host: option("-h", "--host", string()), workers: option("-w", "--workers", integer()) }), { server: false as const } as const ); const globalOptions = object({ verbose: option("-v", "--verbose"), config: option("-c", "--config", string()) }); const appConfig = merge(serverMode, globalOptions); // Usage examples: // myapp -v -c config.json → server mode disabled // myapp -s -p 8080 -h localhost -v → server mode with port and host // myapp -s -p 3000 -w 4 -c prod.json → full server configuration ~~~~ ### Type inference and merging The `merge()` parser intelligently combines the types of all merged parsers, regardless of their original parser type: ~~~~ typescript twoslash import { merge, object } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { integer } from "@optique/core/valueparser"; // ---cut-before--- const basicOptions = object({ verbose: option("-v", "--verbose"), quiet: option("-q", "--quiet") }); const advancedOptions = object({ timeout: option("--timeout", integer()), retries: option("--retries", integer()) }); const allOptions = merge(basicOptions, advancedOptions); type Options = InferValue; // ^? // Type automatically inferred as above. ~~~~ When combining different parser types, the merge result maintains full type safety while accounting for the unique characteristics of each parser: ~~~~ typescript twoslash import { merge, object } from "@optique/core/constructs"; import { map, withDefault } from "@optique/core/modifiers"; import type { InferValue } from "@optique/core/parser"; import { flag, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; // ---cut-before--- const conditionalFeatures = withDefault( object({ experimental: flag("--experimental"), debugLevel: option("--debug-level", integer()) }), { experimental: false as const } as const ); const transformedSettings = map( object({ theme: option("--theme", string()), lang: option("--language", string()) }), ({ theme, lang }) => ({ locale: `${lang}_${theme.toUpperCase()}`, settings: { theme, lang } }) ); const complexConfig = merge( conditionalFeatures, transformedSettings, object({ version: option("--version", string()) }) ); type ComplexConfig = InferValue; // ^? // Type automatically inferred with conditional fields and transformations. ~~~~ ### Optional parser groups *This feature is available since Optique 0.9.0.* The `merge()` parser supports `optional()` wrappers around object-generating parsers. This allows you to define groups of mutually exclusive options that may or may not be provided: ~~~~ typescript twoslash import { merge, object, or } from "@optique/core/constructs"; import { map, multiple, optional } from "@optique/core/modifiers"; import { argument, flag } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // Mutually exclusive verbosity flags wrapped in optional() const verbosityOptions = optional( or( object({ verbosity: optional( map(multiple(flag("--verbose", "-v")), (v) => v.length), ), }), object({ verbosity: optional(map(flag("--quiet", "-q"), () => 0)), }), ), ); // Combine with required positional argument const parser = merge( verbosityOptions, object({ file: argument(string()) }), ); // Usage examples: // myapp file.txt → { file: "file.txt" } // myapp --verbose file.txt → { verbosity: 1, file: "file.txt" } // myapp -v -v -v file.txt → { verbosity: 3, file: "file.txt" } // myapp --quiet file.txt → { verbosity: 0, file: "file.txt" } ~~~~ When using `optional()` in `merge()`: - If the inner parser matches, its result is merged into the final object - If the inner parser doesn't match (no input consumed), parsing continues with the next parser in the merge - The state from matched parsers is preserved across parse iterations The same behavior applies to `withDefault()`, which provides a fallback value when the inner parser doesn't match. This pattern is particularly useful when you have optional feature groups that should not interfere with other required arguments: ~~~~ typescript twoslash import { merge, object, or } from "@optique/core/constructs"; import { map, optional } from "@optique/core/modifiers"; import { argument, constant, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // Optional output format selection const outputOptions = optional( or( object({ format: map(option("--json", string()), () => "json" as const), pretty: constant(undefined), }), object({ format: constant("text" as const), pretty: option("--pretty"), }), ), ); // Main command structure const command = merge( outputOptions, object({ input: argument(string({ metavar: "FILE" })), }), ); // Usage: // myapp data.txt → { input: "data.txt" } // myapp --json schema data.txt → { format: "json", input: "data.txt" } // myapp --pretty data.txt → { format: "text", pretty: true, input: "data.txt" } ~~~~ `concat()` parser ----------------- *This API is available since Optique 0.2.0.* The `concat()` parser combines multiple `tuple()` parsers into a single unified parser, enabling modular tuple design through reusable tuple groups. This is the tuple equivalent of `merge()` for objects, providing compositional flexibility for sequential, positional argument structures. > [!IMPORTANT] > TypeScript overload inference for `concat()` supports up to 15 parser > arguments. Calls beyond 15 now fail at compile time with an actionable > message. For 16+ parsers, split into nested groups so each `concat()` call > stays at 15 or fewer arguments. ~~~~ typescript twoslash import { concat, tuple } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; // Define reusable tuple groups const basicFlags = tuple([ option("-v", "--verbose"), option("-q", "--quiet"), ] as const); const serverConfig = tuple([ option("-p", "--port", integer({ min: 1, max: 0xffff })), option("-h", "--host", string()), ] as const); const logConfig = tuple([ option("--log-level", string()), option("--log-file", string()), ] as const); // Combine tuples for different application modes const webServer = concat(basicFlags, serverConfig); const fullServer = concat(basicFlags, serverConfig, logConfig); const result = parse(fullServer, [ "-v", "-p", "8080", "-h", "localhost", "--log-level", "info", "--log-file", "app.log" ]); if (result.success) { const [verbose, quiet, port, host, logLevel, logFile] = result.value; console.log(`Server: ${host}:${port}, verbose: ${verbose}.`); console.log(`Logging: ${logLevel} to ${logFile}.`); } ~~~~ ### Type concatenation The `concat()` parser intelligently flattens the types of all concatenated tuple parsers into a single tuple type: ~~~~ typescript twoslash import { concat, tuple } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { integer, string } from "@optique/core/valueparser"; // ---cut-before--- const userInfo = tuple([ option("-n", "--name", string()), option("-a", "--age", integer()), ] as const); const preferences = tuple([ option("-t", "--theme", string()), option("-v", "--verbose"), ] as const); const combined = concat(userInfo, preferences); type CombinedType = InferValue; // ^? // Type automatically inferred as above. ~~~~ ### Usage patterns Concatenation is useful when you need: - Modular tuple construction from reusable components - Sequential argument processing with clear grouping - Building complex CLIs from simpler tuple building blocks - Maintaining positional semantics across grouped options ~~~~ typescript twoslash import { concat, tuple } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { argument, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; // ---cut-before--- // Build authentication tuple const authTuple = tuple([ option("-u", "--user", string()), option("-p", "--pass", string()), ] as const); // Build connection tuple const connectionTuple = tuple([ option("--host", string()), option("--port", integer()), option("--ssl"), ] as const); // Build command arguments tuple const commandTuple = tuple([ argument(string()), // command name argument(string()), // target file ] as const); // Combine all for a database client const dbClient = concat(authTuple, connectionTuple, commandTuple); // Usage: myapp -u admin -p secret --host db.example.com --port 5432 --ssl backup users.sql const config = parse(dbClient, [ "-u", "admin", "-p", "secret", "--host", "db.example.com", "--port", "5432", "--ssl", "backup", "users.sql" ]); if (config.success) { const [user, pass, host, port, ssl, command, file] = config.value; console.log(`Connecting as ${user} to ${host}:${port}.`); console.log(`Running ${command} on ${file}.`); } ~~~~ ### Relationship to `merge()` While `merge()` combines object parsers by merging their properties, `concat()` combines tuple parsers by flattening their positional elements: | Combinator | Input parsers | Result type | | ---------- | ------------------ | --------------------------------- | | `merge()` | `object()` parsers | Merged object with all properties | | `concat()` | `tuple()` parsers | Flattened tuple with all elements | Both provide compositional design patterns but serve different structural needs in CLI applications. `longestMatch()` parser ----------------------- *This API is available since Optique 0.3.0.* The `longestMatch()` parser combines multiple mutually exclusive parsers by selecting the parser that consumes the most input tokens. Unlike `or()` which returns the first successful match, `longestMatch()` tries all parsers and selects the one with the longest match. This enables context-aware parsing where more specific patterns take precedence over general ones. > [!IMPORTANT] > TypeScript overload inference for `longestMatch()` supports up to 15 parser > arguments. Calls beyond 15 now fail at compile time with an actionable > message. For 16+ parsers, split into nested groups so each > `longestMatch()` call stays at 15 or fewer arguments. ~~~~ typescript twoslash import { longestMatch, object } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { argument, constant, flag } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; const globalHelp = object({ type: constant("global"), help: flag("--help"), }); const contextualHelp = object({ type: constant("contextual"), command: argument(string({ metavar: "COMMAND" })), help: flag("--help"), }); const parser = longestMatch(globalHelp, contextualHelp); type Result = InferValue; // ^? // Usage examples: // myapp --help → globalHelp (1 token: --help) // myapp list --help → contextualHelp (2 tokens: list --help) ~~~~ ### Longest match selection The key behavior of `longestMatch()` is selecting the parser that consumes the most tokens from the input: ~~~~ typescript twoslash import { longestMatch, object } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { argument, constant, flag } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- const shortPattern = object({ type: constant("short"), help: flag("--help"), }); const longPattern = object({ type: constant("long"), command: argument(string()), help: flag("--help"), }); const parser = longestMatch(shortPattern, longPattern); // Short pattern matches: consumes 1 token (--help) const shortResult = parse(parser, ["--help"]); if (shortResult.success) { console.log(shortResult.value.type); // "short" } // Long pattern matches: consumes 2 tokens (list --help) const longResult = parse(parser, ["list", "--help"]); if (longResult.success) { console.log(longResult.value.type); // "long" } ~~~~ ### Context-aware help systems The most common use case for `longestMatch()` is implementing context-aware help systems where `command --help` shows help for that specific command: ~~~~ typescript twoslash import { longestMatch, object, or } from "@optique/core/constructs"; import { multiple, optional } from "@optique/core/modifiers"; import { argument, command, constant, flag, option, } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- // Define your application commands const addCommand = command( "add", object({ action: constant("add"), key: argument(string({ metavar: "KEY" })), value: argument(string({ metavar: "VALUE" })), }), ); const listCommand = command( "list", object({ action: constant("list"), pattern: optional( option("-p", "--pattern", string({ metavar: "PATTERN" })), ), }), ); // Normal command parsing const normalParser = object({ help: constant(false), result: or(addCommand, listCommand), }); // Context-aware help parsing const contextualHelpParser = object({ help: constant(true), commands: multiple(argument(string({ metavar: "COMMAND" }))), flag: flag("--help"), }); // Combine with longestMatch for intelligent help selection const parser = longestMatch(normalParser, contextualHelpParser); // Normal usage works as expected: // myapp add key1 value1 → normalParser (3 tokens) // myapp list -p "*.txt" → normalParser (3 tokens) // Context-aware help automatically activates: // myapp list --help → contextualHelpParser (2 tokens: ["list"]) // myapp add --help → contextualHelpParser (2 tokens: ["add"]) ~~~~ ### Type inference and unions Like `or()`, `longestMatch()` creates discriminated union types when used with parsers that produce different shaped objects: ~~~~ typescript twoslash import { longestMatch, object } from "@optique/core/constructs"; import { type InferValue, parse } from "@optique/core/parser"; import { constant, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; // ---cut-before--- const stringMode = object({ mode: constant("string" as const), value: option("-s", "--string", string()), }); const numberMode = object({ mode: constant("number" as const), value: option("-n", "--number", integer()), }); const parser = longestMatch(stringMode, numberMode); type Config = InferValue; // ^? // Type-safe pattern matching const result = parse(parser, ["-s", "hello"]); if (result.success) { switch (result.value.mode) { case "string": // TypeScript knows this is string config console.log(`String value: ${result.value.value}.`); break; case "number": // TypeScript knows this is number config console.log(`Number value: ${result.value.value}.`); break; } } ~~~~ ### Allowed duplicates in `longestMatch()` Like `or()`, `longestMatch()` allows duplicate option names across branches. This is intentional: the branches are still mutually exclusive, and only the selected branch contributes to the final result. When multiple branches share the same option names, `longestMatch()` selects the branch that consumes the most input tokens. If two branches consume the same number of tokens, the first matching branch wins. ~~~~ typescript twoslash import { longestMatch, object } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { constant, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- const parser = longestMatch( object({ mode: constant("basic" as const), format: option("--format", string()), }), object({ mode: constant("advanced" as const), format: option("--format", string()), profile: option("--profile", string()), }), ); const result = parse(parser, [ "--format", "json", "--profile", "prod", ]); // Chooses the second branch because it consumes more tokens. // If both branches consumed the same number of tokens, // the first matching branch would win. ~~~~ ### Usage patterns and best practices Use `longestMatch()` when you need: - *Context-aware behavior*: Different parsing based on how much input is consumed - *Precedence by specificity*: More specific patterns should win over general ones - *Greedy matching*: Always prefer the parser that consumes the most tokens - *Help system integration*: Context-sensitive help that shows relevant information ~~~~ typescript twoslash import { longestMatch, object, or } from "@optique/core/constructs"; import { multiple, optional } from "@optique/core/modifiers"; import { argument, command, constant, flag, option, } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- // Example: Git-like CLI with context-aware help const gitAdd = command("add", object({ action: constant("add"), files: multiple(argument(string())), all: optional(option("-A", "--all")), })); const gitCommit = command("commit", object({ action: constant("commit"), message: option("-m", "--message", string()), })); const normalCommands = object({ help: constant(false), command: or(gitAdd, gitCommit), }); const helpParser = object({ help: constant(true), commands: multiple(argument(string())), helpFlag: flag("--help"), }); const cli = longestMatch(normalCommands, helpParser); // Usage patterns: // git add file.txt --all → normalCommands (gitAdd) // git commit -m "message" → normalCommands (gitCommit) // git add --help → helpParser (commands: ["add"]) // git commit --help → helpParser (commands: ["commit"]) // git --help → helpParser (commands: []) ~~~~ ### Relationship to other combinators | Combinator | Selection strategy | Use case | | ---------------- | ---------------------- | -------------------------------- | | `or()` | First successful match | Mutually exclusive alternatives | | `longestMatch()` | Most tokens consumed | Context-aware and greedy parsing | | `merge()` | Combines all parsers | Composing complementary parsers | The `longestMatch()` combinator bridges the gap between simple alternatives (`or()`) and complex composition (`merge()`) by providing intelligent selection based on input consumption. `conditional()` parser ---------------------- *This API is available since Optique 0.8.0.* The `conditional()` parser creates a discriminated union based on a discriminator option value. This enables context-dependent parsing where certain options are only valid when a specific discriminator value is selected. ~~~~ typescript twoslash import { conditional, object } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { choice, string } from "@optique/core/valueparser"; const parser = conditional( option("--reporter", choice(["console", "junit", "html"])), { console: object({}), junit: object({ outputFile: option("--output-file", string()) }), html: object({ outputFile: option("--output-file", string()) }), } ); type Result = InferValue; // ^? // Type automatically inferred as discriminated tuple union. ~~~~ ### Discriminator-based branching The key behavior of `conditional()` is selecting the appropriate branch parser based on the discriminator value. The result is a tuple containing the discriminator value and the branch result: ~~~~ typescript twoslash import { conditional, object } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { choice, string } from "@optique/core/valueparser"; // ---cut-before--- const parser = conditional( option("--format", choice(["json", "xml"])), { json: object({ pretty: option("--pretty") }), xml: object({ indent: option("--indent", string()) }), } ); // When --format json is provided const jsonResult = parse(parser, ["--format", "json", "--pretty"]); if (jsonResult.success) { const [format, options] = jsonResult.value; if (format === "json") { // TypeScript knows options is { pretty: boolean } console.log(`Format: ${format}, Pretty: ${options.pretty}.`); } } // When --format xml is provided const xmlResult = parse(parser, ["--format", "xml", "--indent", " "]); if (xmlResult.success) { const [format, options] = xmlResult.value; if (format === "xml") { // TypeScript knows options is { indent: string } console.log(`Format: ${format}, Indent: "${options.indent}".`); } } ~~~~ ### Default branch When a default branch is provided, the discriminator becomes optional. If the discriminator is not specified, the default branch is used: ~~~~ typescript twoslash import { conditional, object } from "@optique/core/constructs"; import type { InferValue } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { choice, string } from "@optique/core/valueparser"; // ---cut-before--- const parser = conditional( option("--reporter", choice(["junit", "html"])), { junit: object({ outputFile: option("--output-file", string()) }), html: object({ outputFile: option("--output-file", string()) }), }, object({ format: option("--format", string()) }) // Default branch ); type Result = InferValue; // Default branch result has undefined as discriminator value. ~~~~ When the discriminator is not provided, the result tuple has `undefined` as the first element: ~~~~ typescript twoslash import { conditional, object } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { choice, string } from "@optique/core/valueparser"; const parser = conditional( option("--reporter", choice(["junit", "html"])), { junit: object({ outputFile: option("--output-file", string()) }), html: object({ outputFile: option("--output-file", string()) }), }, object({ format: option("--format", string()) }) ); // ---cut-before--- // Without --reporter, default branch is used const result = parse(parser, ["--format", "text"]); if (result.success) { const [reporter, options] = result.value; if (reporter === undefined) { // Default branch - options is { format: string } console.log(`Using default format: ${options.format}.`); } } ~~~~ ### Required discriminator (no default) When no default branch is provided, the discriminator is required. If it's missing, an error is returned: ~~~~ typescript twoslash import { conditional, object } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { choice, string } from "@optique/core/valueparser"; // ---cut-before--- const parser = conditional( option("--reporter", choice(["junit", "html"])), { junit: object({ outputFile: option("--output-file", string()) }), html: object({ outputFile: option("--output-file", string()) }), } // No default branch - discriminator is required ); const result = parse(parser, ["--output-file", "report.xml"]); // Error: Missing required option --reporter. ~~~~ ### Type-safe pattern matching The `conditional()` parser enables type-safe pattern matching based on the discriminator value: ~~~~ typescript twoslash import { conditional, object } from "@optique/core/constructs"; import { parse } from "@optique/core/parser"; import { option } from "@optique/core/primitives"; import { choice, string, integer } from "@optique/core/valueparser"; const parser = conditional( option("--db", choice(["sqlite", "postgres", "mysql"])), { sqlite: object({ file: option("--file", string()) }), postgres: object({ host: option("--host", string()), port: option("--port", integer()), }), mysql: object({ host: option("--host", string()), port: option("--port", integer()), }), } ); // ---cut-before--- const result = parse(parser, ["--db", "postgres", "--host", "localhost", "--port", "5432"]); if (result.success) { const [db, config] = result.value; if (db === "sqlite") { // TypeScript knows config is { file: string } console.log(`SQLite database file: ${config.file}.`); } else if (db === "postgres") { // TypeScript knows config is { host: string, port: number } console.log(`PostgreSQL server at ${config.host}:${config.port}.`); } else if (db === "mysql") { // TypeScript knows config is { host: string, port: number } console.log(`MySQL server at ${config.host}:${config.port}.`); } } ~~~~ ### Relationship to `or()` The `conditional()` parser provides a more structured alternative to `or()` for discriminated union patterns: | Feature | `or()` | `conditional()` | | ---------------- | ------------------------ | ----------------------------------- | | Discriminator | Manual with `constant()` | Explicit discriminator option | | Branch selection | First matching parser | Based on discriminator value | | Result type | Union of branch types | Tuple `[discriminator, branchType]` | | Default handling | Via parser ordering | Explicit default branch | | Type narrowing | Via discriminator field | Via tuple first element | Use `conditional()` when you have an explicit discriminator option that determines which set of options is valid. Use `or()` for more general mutually exclusive alternatives. ### Speculative branch parsing When the discriminator is an async parser that succeeds without consuming input (e.g., `prompt(option(...))` with no CLI input), branch selection is normally deferred to the complete phase. To allow branch-specific tokens to be consumed, `conditional()` speculatively tries all named branches during parse. If exactly one branch can consume tokens, it is tentatively selected and verified against the resolved discriminator during the complete phase. If the discriminator resolves to a different branch than the one that consumed tokens (contradictory input), the parse fails. When multiple branches can consume the same tokens (ambiguous), speculation is skipped entirely to keep branch selection order-independent. Speculation works best when named branches have distinct leading options (e.g., `--threads` vs `--timeout`). When a default branch accepts the same tokens as a named branch, or when the parser is nested inside `longestMatch()`, the speculative choice may conflict with the discriminator. To avoid this, ensure named branch options are distinct from the default branch, or wrap the discriminator with `withDefault()` or `bindEnv()` so it can resolve synchronously. `group()` parser ---------------- *This API is available since Optique 0.4.0.* The `group()` parser is a documentation-only wrapper that applies a group label to any parser for help text organization. This allows you to maintain clean code structure with combinators like `or()`, `flag()`, or `multiple()` while providing well-organized help output through group labeling. Unlike `merge()` and `object()` which have built-in label support, many parsers don't natively support labeling. The `group()` parser fills this gap by wrapping any parser with a labeled section that appears in help documentation. ~~~~ typescript twoslash import { group, or } from "@optique/core/constructs"; import { map, multiple } from "@optique/core/modifiers"; import { argument, flag } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // Group mutually exclusive output format options const outputFormat = group( "Output Format", or( map(flag("--json"), () => "json" as const), map(flag("--yaml"), () => "yaml" as const), map(flag("--xml"), () => "xml" as const), ), ); // Group multiple file inputs const inputFiles = group( "Input Files", multiple(argument(string({ metavar: "FILE" })), { min: 1 }), ); // The labels "Output Format" and "Input Files" will appear as // section headers in help text, organizing related options ~~~~ ### Documentation-only wrapper The `group()` parser has identical parsing behavior to its wrapped parser. All parsing operations, state management, and type information are preserved unchanged: ~~~~ typescript twoslash import { group, or } from "@optique/core/constructs"; import { map } from "@optique/core/modifiers"; import { type InferValue, parse } from "@optique/core/parser"; import { flag } from "@optique/core/primitives"; const formatParser = or( map(flag("--json"), () => "json" as const), map(flag("--yaml"), () => "yaml" as const), ); const groupedParser = group("Format Options", formatParser); // Type inference is preserved type FormatType = InferValue; // ^? // Parsing behavior is identical const result1 = parse(formatParser, ["--json"]); const result2 = parse(groupedParser, ["--json"]); if (result1.success && result2.success) { // Both produce the same result console.assert(result1.value === result2.value); // "json" } ~~~~ ### Grouping commands Wrap a command dispatcher in `group()` to give the command list a heading without labeling the selected command's options: ~~~~ typescript twoslash import { group, object, or } from "@optique/core/constructs"; import { message } from "@optique/core/message"; import { optional } from "@optique/core/modifiers"; import { command, constant, option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; const logs = optional(option("-L", "--logs", string({ metavar: "DIR" }), { description: message`Logs directory`, })); const parser = group("Commands", or( command("list", object({ action: constant("list"), logs }), { brief: message`List run directories`, }), command("rotate", object({ action: constant("rotate"), logs }), { brief: message`Rotate run directories`, }), )); ~~~~ The parent help page includes this section: ~~~~ text Commands: list List run directories rotate Rotate run directories ~~~~ On the `list` help page, the options appear without the outer heading: ~~~~ text -L, --logs DIR Logs directory ~~~~ The outer label also stops applying when the selected command exposes its own nested commands. Explicit groups inside a command keep their own titles. A labeled `object("Commands", { command: or(...) })` or `merge("Commands", ...)` keeps its label when its children expose the selected command's options. Use `group("Commands", or(...))` when the heading belongs to the command list only. A labeled `object()` or `merge()` used as a command body keeps its heading on that command's own help page too. For options shared by every command, see [shared options across subcommands](../cookbook.md#shared-options-across-subcommands). Grouping the shared options gives them a heading on both the parent and subcommand help pages. For headings only on pages with commands, use the runner's [`helpSections`](./runners.md#automatic-help-sections) setting instead. ### Realistic usage patterns The `group()` parser is most useful with parsers that don't have built-in labeling support: ~~~~ typescript twoslash import { group, or, object } from "@optique/core/constructs"; import { map, multiple, optional, withDefault } from "@optique/core/modifiers"; import { argument, flag, option } from "@optique/core/primitives"; import { string, integer } from "@optique/core/valueparser"; // ---cut-before--- // Logging level selection (mutually exclusive) const loggingOptions = group( "Logging Options", or( map(flag("--debug"), () => "debug" as const), map(flag("--verbose"), () => "verbose" as const), map(flag("--quiet"), () => "quiet" as const), ), ); // Multiple input files const inputSources = group( "Input Sources", multiple(argument(string({ metavar: "FILE" })), { min: 1 }), ); // Optional output configuration const outputConfig = group( "Output Configuration", optional(option("--output", string({ metavar: "PATH" }))), ); // Single debug flag const debugMode = group( "Debug Mode", flag("--debug-mode"), ); // Default server configuration const serverSettings = group( "Server Configuration", withDefault( object({ port: option("--port", integer()), host: option("--host", string()), }), { port: 3000, host: "localhost" }, ), ); ~~~~ ### Help text organization The primary benefit of `group()` is organizing help output into logical sections: ~~~~ ansi Usage: myapp (--debug | --verbose | --quiet) [--output PATH] --debug-mode [--port INTEGER --host STRING] FILE... Logging Options: --debug --verbose --quiet Output Configuration: --output PATH Debug Mode: --debug-mode Server Configuration: --port INTEGER --host STRING Input Sources: FILE ~~~~ Without `group()`, these options would appear as a flat list without clear organization, making it harder for users to understand the relationship between related options. ### Nested groups The `group()` parser supports nesting, allowing you to create hierarchical documentation structures: ~~~~ typescript twoslash import { group, object } from "@optique/core/constructs"; import { flag, option } from "@optique/core/primitives"; import { integer } from "@optique/core/valueparser"; // ---cut-before--- const debugOptions = object({ verbose: flag("--verbose"), trace: flag("--trace"), }); const serverOptions = object({ port: option("--port", integer()), workers: option("--workers", integer()), }); // First level grouping const innerDebugGroup = group("Debug Options", debugOptions); const innerServerGroup = group("Server Options", serverOptions); // Second level grouping const applicationConfig = group("Application Configuration", object({ debug: innerDebugGroup, server: innerServerGroup, })); // This creates a nested structure in help documentation ~~~~ ### Best practices Use `group()` when you need: - *Section organization*: Grouping related options under meaningful headers - *Parser flexibility*: Labeling parsers that don't have built-in label support - *Help text clarity*: Making complex CLIs more user-friendly - *Clean code structure*: Maintaining modular parser composition ~~~~ typescript twoslash import { group, object, or } from "@optique/core/constructs"; import { map, multiple, withDefault } from "@optique/core/modifiers"; import { argument, flag, option } from "@optique/core/primitives"; import { string, integer, choice } from "@optique/core/valueparser"; // ---cut-before--- // Example: File processing tool with organized help const processingMode = group( "Processing Mode", or( map(flag("--compress"), () => "compress" as const), map(flag("--extract"), () => "extract" as const), map(flag("--list"), () => "list" as const), ), ); const compressionSettings = group( "Compression Settings", object({ level: withDefault( option("--level", integer({ min: 1, max: 9 })), 6, ), algorithm: withDefault( option("--algorithm", choice(["gzip", "bzip2", "xz"])), "gzip", ), }), ); const inputOutput = group( "Input/Output", object({ input: multiple(argument(string({ metavar: "INPUT_FILE" })), { min: 1 }), output: option("-o", "--output", string({ metavar: "OUTPUT_FILE" })), }), ); // Each group appears as a distinct section in help text, // making the CLI interface much more approachable ~~~~ Duplicate option detection -------------------------- Optique automatically detects and prevents duplicate option names within parser combinators to avoid ambiguous behavior. When the same option name appears in multiple fields or parsers, parser construction throws an error before parsing begins. This check includes `hidden: true` options because hidden options still consume the same command-line syntax. ### Detected duplicates The `object()`, `tuple()`, and `merge()` combinators validate that option names are unique across their child parsers: ~~~~ typescript twoslash import { object, option } from "@optique/core"; // ---cut-before--- // ❌ This throws while constructing the parser const parser = object({ verbose: option("-v", "--verbose"), version: option("-v", "--version"), // Duplicate: -v }); // Throws DuplicateOptionError because both fields use -v. ~~~~ This applies to nested structures as well: ~~~~ typescript twoslash import { object, option } from "@optique/core"; // ---cut-before--- // ❌ Nested duplicate detected const parser = object({ opts: object({ verbose: option("-v"), }), flags: object({ version: option("-v"), // Duplicate across nested objects }), }); ~~~~ Hidden options are checked the same way: ~~~~ typescript twoslash import { object, option } from "@optique/core"; import { string } from "@optique/core/valueparser"; // ---cut-before--- const parser = object({ legacy: option("--output", string(), { hidden: true }), current: option("--output", string()), }); // Throws DuplicateOptionError because both fields use --output. // Hidden options still participate in parsing. ~~~~ ### Allowed duplicates in `or()` The `or()` combinator allows duplicate option names because branches are mutually exclusive—only one branch can match: ~~~~ typescript twoslash import { or, option } from "@optique/core"; import { parse } from "@optique/core/parser"; // ---cut-before--- // ✅ This is valid - branches are mutually exclusive const parser = or( option("-v", "--verbose"), option("-v", "--version"), ); const result = parse(parser, ["-v"]); // First matching branch wins ~~~~ ### Opting out with `allowDuplicates` For advanced use cases, you can disable duplicate detection using the `allowDuplicates` option: ~~~~ typescript twoslash import { object, option } from "@optique/core"; import { parse } from "@optique/core/parser"; // ---cut-before--- const parser = object({ verbose: option("-v", "--verbose"), version: option("-v", "--version"), }, { allowDuplicates: true }); const result = parse(parser, ["-v"]); // Succeeds - first parser wins ~~~~ > [!CAUTION] > Using `allowDuplicates` can lead to unpredictable behavior where the first > matching parser consumes the option and subsequent parsers receive their > default values. Only use this option when you fully understand the > implications.