Differentiate between options withDefault() vs option passed explicitly by the user

[rj-elias]

I am trying to differentiate options passed explicitly vs option pass with withDefault()

> optique
> optique [options]
> optique <command>
> optique <command> [options]

Here is my setup

// Values
const help = option("-h", "--help")
const version = option("-v", "--version")
const cwd = option("-c", "--cwd", path())

// Options called from the root
// > optique --help
// > optique --version"
const rootOptions = object({
   loc: constant("root"),
   version: optional(version),
   help: optional(help),
})

// Global options merged with all commands
const globalOptions = object("Global options", {
   help: optional(help),
   cwd: optional(cwd),
})

// Command options
const devOptions = object({
   loc: constant("dev"),
   key: optional(key),
   env: optional(env),
})
// ...

// Commands
const devCmd = merge(devOptions, globalOptions)
const buildCmd = merge(buildOptions, globalOptions)
// ...
const commands = or(devCmd, buildCmd, ...<other commands>)

// Root parser
export const parser = or(rootOptions, commands)

Now here are the use cases

// optique --help
// I test for help: true to print the global hep
{
  success: true,
  value: { loc: 'root', version: undefined, help: true }
}

// optique dev --help
// I test for loc: dev and hep: true to print the dev help
{
  success: true,
  value: {
    loc: 'dev',
    key: undefined,
    env: undefined,
    help: true,
    cwd: undefined
  }
}

// optique dev
// Here I can test all options to be undefined to conclude that no options have been passed to the dev command
// Then chose that no option passed to the command is equivalent to --help and print the dev help 
{
  success: true,
  value: {
    loc: 'dev',
    key: undefined,
    env: undefined,
    help: undefined,
    cwd: undefined
  }
}

The problem is when I introduce withDefault()

export const cwd = withDefault(option("-c", "--cwd", path()), process.cwd())

// optique dev
{
  success: true,
  value: {
    loc: 'dev',
    key: undefined
    env: undefined
    help: undefined,
    cwd: '/path/to/current/working/directory'
  }
}

optique dev Here the cwd has not been passed by the user, the intent is to show the help page
optique dev --cwd ./ Here cwd has been passed by the user explicitly, the command does something

But currently the response is the same

[dahlia]

Hi! You can use optional() instead of withDefault() to distinguish between these two cases.

The difference

• optional(): Returns undefined when the parser fails to match

  • optique dev → { cwd: undefined }
  • optique dev --cwd ./ → { cwd: "./" }
  • You can distinguish between the two cases ✓

• withDefault(): Returns the default value when the parser fails to match

  • optique dev → { cwd: "./" } (default value)
  • optique dev --cwd ./ → { cwd: "./" } (user input)
  • You cannot distinguish between the two cases ✗

Example

import { object } from "@optique/core/constructs";
import { optional } from "@optique/core/modifiers";
import { parse } from "@optique/core/parser";
import { option } from "@optique/core/primitives";
import { string } from "@optique/core/valueparser";

const parser = object({
  cwd: optional(option("--cwd", string()))
});

const result = parse(parser, args);

if (result.success) {
  if (result.value.cwd === undefined) {
    // No options provided → show help
    console.log("Please provide --cwd option");
    showHelp();
  } else {
    // User explicitly provided a value → use it
    runCommand(result.value.cwd);
  }
}

The optional() modifier makes the parser return undefined when no value is provided, allowing you to detect when the user hasn't specified the option.

See the documentation for more details:

• optional() parser
• withDefault() parser

[eakl]

Thanks dahlia for the answer. (I'm the same person as above)

Actually my goal is a bit different.

I could do optional() on every options and test in the handler whether all options are undefined to conclude to "no option were passed" vs. "at least one option is defined"

What I'm trying to do is different.

I want to apply WithDefault conditionally.

1. cli dev => no option were passed => no default apply => show man page
2. cli dev [at least one option] => an option has been passed but not cwd => assign cwd a default and run the command
3. cli dev [any option] --cwd ... => cwd has been passed => overwrite cwd and run the command.

[dahlia]

You're right that the current workaround (using optional() on every option and checking in the handler) isn't ideal. I explored several approaches with or(), longestMatch(), and withDefault(), but none of them work with Optique's current design.

Why it doesn't work

The fundamental issue is that Optique doesn't currently provide a way to distinguish between “parser succeeded with zero consumption” and “parser succeeded with at least one token consumed” at the combinator level.

• or() already checks consumed.length > 0 internally, which is why using constant() inside or() doesn't work
• longestMatch() selects based on consumption count but doesn't reject zero-consumption parsers, so when both branches consume zero tokens, it just picks the first one

Solution: nonEmpty() modifier

I've created #79 to add a nonEmpty() modifier that will solve this use case. Once implemented (targeting 0.10.0), you'll be able to write:

import { nonEmpty } from "@optique/core/modifiers";

const parser = longestMatch(
  nonEmpty(object({
    help: constant(false),
    cwd: withDefault(option("--cwd", string()), process.cwd()),
    otherOption: optional(option("--other-option", string())),
  })),
  object({
    help: constant(true),
  })
);

This will give you the exact behavior you want:

1. cli dev → first parser rejected by nonEmpty() (consumed 0 tokens) → second parser selected → { help: true }
2. cli dev --other-option foo → first parser accepted (consumed 2 tokens) → { help: false, cwd: process.cwd(), otherOption: "foo" }
3. cli dev --cwd ./path → first parser accepted → { help: false, cwd: "./path", otherOption: undefined }

I'll work on implementing nonEmpty() soon and let you know when it's available.

[eakl]

Awesome! Thanks.

And by the way, optique's API is beautiful ;)

[dahlia]

@eakl @rj-elias The nonEmpty() modifier has been implemented and can solve your use case. Here's how you can combine it with longestMatch() and withDefault():

import { longestMatch, object } from "@optique/core/constructs";
import { nonEmpty, optional, withDefault } from "@optique/core/modifiers";
import { constant, option } from "@optique/core/primitives";
import { string } from "@optique/core/valueparser";

// This parser requires at least one token to be consumed
const activeParser = nonEmpty(object({
  mode: constant("active" as const),
  cwd: withDefault(
    option("--cwd", string()),
    "./",
  ),
  key: optional(option("--key", string())),
}));

// Falls back to help mode when no options are provided
const helpParser = object({
  mode: constant("help" as const),
});

const parser = longestMatch(activeParser, helpParser);

// cli           → helpParser wins (activeParser fails due to nonEmpty)
// cli --key foo → activeParser wins (consumes tokens)
// cli --cwd .   → activeParser wins (consumes tokens)

Without nonEmpty(), activeParser would always win because it succeeds with zero tokens consumed (all options have defaults or are optional). With nonEmpty(), it fails when no tokens are consumed, allowing helpParser to match instead.

See #79 and #80 for more details on the implementation.

This will be available in version 0.10.0. If you'd like to try it out now, you can use the pre-release version 0.10.0-dev.319.

[rj-elias]

The parser doesn't seem to work inside a command

const parser = command("dev", longestMatch(activeParser, helpParser))
// => cli dev
// {
//   success: false,
//   error: [
//     {
//       type: 'text',
//       text: 'No matching option, command, or argument found.'        
//     }
//   ]
// }

[dahlia]

Thanks for reporting this! You're right, there's a bug when using longestMatch() inside command().

The issue is that command() doesn't properly handle inner parsers that can succeed with zero tokens when the buffer is empty after matching the command name. I've created #81 to track this.

I'll fix it shortly and let you know once it's available.

[dahlia]

The bug has been fixed in #81. You can now try it with pre-release version 0.10.0-dev.323!

[rj-elias]

Thanks dahlia, it works!

Though I have an interesting case that doesn't work and I don't think this is an issue but how the parser works.

My goal

• The CLI has root options (help, version)
• The CLI has global options applied to all commands (cwd)
• The CLI has multiple commands (dev, build, preview, etc...)
• No options provided at the root of the CLI or the root of the command is equivalent to --help

This is my structure

The root parser

export const emptyOptions = object({
   help: constant(true),
})

export const rootOptions = object({
   loc: constant("root"),
   version: optional(version),
   help: optional(help),
})

export const rootParser = longestMatch(
   nonEmpty(rootOptions),
   merge(object({ loc: constant("root") }), emptyOptions)
)

// cli  => { success: true, value: { loc: 'root', help: true } }
// cli -h => { success: true, value: { loc: 'root', version: undefined, help: true } }

The command parsers

const globalOptions = object({
   help: optional(help),
   cwd: withDefault(optional(cwd), process.cwd()),
})

const devOptions = object({
   loc: constant("dev"),
   key: optional(option("--key", string())),
   env: optional(option("--key", string())),
})

const devOptionsFull = merge(devOptions, globalOptions)

const devCmd = command(
   "dev",
   longestMatch(nonEmpty(devOptionsFull), merge(object({ loc: constant("dev") }), emptyOptions))
)

// cli dev => { success: true, value: { loc: 'dev', help: true } }
// cli dev --key hello --cwd ./ => { success: true, value: { loc: 'dev', key: 'hello', help: undefined, cwd: './' } }

The CLI

const cmdParser = or(devCmd, buildCmd)
const parser = or(rootParser, cmdParser) // THIS BREAKS

// cli  => { success: false, error: [ { type: 'text', text: 'No matching command found.' } ] }
// cli -h => { success: true, value: { loc: 'root', version: undefined, help: true } }
// cli dev => { success: true, value: { loc: 'dev', help: true } }
// cli dev --key hello --cwd ./ => { success: true, value: { loc: 'dev', key: 'hello', help: undefined, cwd: './' } }

As you can see, cli alone breaks because it expects a command.

The docs states

The or() parser creates mutually exclusive alternatives, trying each alternative in order until one succeeds.

Shouldn't parser succeed with no option like the standalone rootParser does if or() tries parsers in order?

[dahlia]

Yes, or() does assume that at least one token must be consumed for a parser to be “selected.” This is documented in the constructs documentation:

Note

The or() parser requires that at least one of its alternatives consumes input to determine which parser branch was “selected.” If no input is provided and none of the alternatives match, or() returns an error.

Looking at your code structure:

const rootParser = longestMatch(
   nonEmpty(rootOptions),
   merge(object({ loc: constant("root") }), emptyOptions)
)

const cmdParser = or(devCmd, buildCmd)
const parser = or(rootParser, cmdParser) // This breaks

When you run cli with no arguments:

1. or() tries rootParser first

2. rootParser succeeds (via the second branch of longestMatch) but consumes 0 tokens

3. or() sees 0 tokens consumed and rejects this match:

   optique/packages/core/src/constructs.ts

   Line 1277 in 5bba27e

   if (result.success && result.consumed.length > 0) {

4. or() tries cmdParser next

5. cmdParser also fails

6. Result: “No matching command found” error

The issue is that or() is designed for mutually exclusive alternatives that must consume input, not for optional parsing scenarios.

Solution

Instead of wrapping everything in or(), structure your parser so that the root-level longestMatch() is at the top level:

const emptyOptions = object({
   help: constant(true),
})

const rootOptions = object({
   loc: constant("root"),
   version: optional(version),
   help: optional(help),
})

const devOptions = object({
   loc: constant("dev"),
   key: optional(option("--key", string())),
   env: optional(option("--env", string())),
})

const globalOptions = object({
   help: optional(help),
   cwd: withDefault(optional(cwd), process.cwd()),
})

const devOptionsFull = merge(devOptions, globalOptions)

const devCmd = command(
   "dev",
   longestMatch(nonEmpty(devOptionsFull), merge(object({ loc: constant("dev") }), emptyOptions))
)

// Instead of or(rootParser, cmdParser), use longestMatch at the top level:
const parser = longestMatch(
   or(devCmd, buildCmd), // Commands branch
   nonEmpty(rootOptions), // Root options branch
   merge(object({ loc: constant("root") }), emptyOptions) // Empty input fallback
)

This way:

• cli → third branch (empty input, shows help)
• cli -h → second branch (root options)
• cli dev → first branch, devCmd's second alternative (shows dev help)
• cli dev --key hello → first branch, devCmd's first alternative (runs command)

The key insight is that longestMatch() allows zero-consumption parsers at the top level, while or() does not.

[rj-elias]

Thanks for the answer. Though cli <command> doesn't seem with your proposed solution

> cli dev
> cli dev --key hello
> cli dev --env staging
// {
//    success: false,
//    error: [
//       { type: 'text', text: 'Unexpected option or subcommand: ' },
//       { type: 'optionName', optionName: 'dev' },
//       { type: 'text', text: '.' }
//    ]
// }

[dahlia]

Interesting… I tested the proposed solution with multiple commands and all cases work correctly in my testing:

const devCmd = command(
  "dev",
  longestMatch(nonEmpty(devOptionsFull), merge(object({ loc: constant("dev") }), emptyOptions))
);

const buildCmd = command(
  "build",
  longestMatch(nonEmpty(buildOptionsFull), merge(object({ loc: constant("build") }), emptyOptions))
);

const parser = longestMatch(
  or(devCmd, buildCmd), // Commands branch
  nonEmpty(rootOptions), // Root options branch
  merge(object({ loc: constant("root") }), emptyOptions) // Empty input fallback
);

// All tests pass:
// cli dev                → { loc: "dev", help: true }
// cli dev --key hello    → { loc: "dev", key: "hello", ... }
// cli dev --env staging  → { loc: "dev", env: "staging", ... }

Could you share the exact parser code you're using? The error message “Unexpected option or subcommand: dev” suggests that:

1. The devCmd might not be included in the or() combinator, or
2. The command() wrapper might be missing from one of the commands, or
3. There might be a different parser structure than what I proposed

If you share your full parser definition, I can identify the exact issue.

[rj-elias]

It was my setup sorry. It actually works like a charm. Thanks for the help.