Migrating an option value from boolean to choices requires breaking changes

Related: yargs/yargs#1599

Boolean options have this special property:

If a non-flag option - unless true or false - follows key in process.argv, that string won’t get set as the value of key.

This means that if a CLI defines an option as a boolean, it isn't currently possible to later change that option to support more choices than true or false without creating a breaking change for the CLI's interface.

In other words, this happens currently:

require('yargs-parser')('--foo bar')
> { _: [], foo: 'bar' }

require('yargs-parser')('--foo bar', { boolean: ['foo'] })
> { _: [ 'bar' ], foo: true }

If the choices option were handled already in the parser, it'd be possible to (optionally?) allow similar behaviour for it:

require('yargs-parser')('--foo bar', {
  choices: ['true', 'false', 'maybe'], // not a current parser option
  default: { foo: 'maybe' }
})
> { _: [ 'bar' ], foo: 'maybe' }

A similar result could also be achieved if the coerce function could indicate that the given value should not be consumed for the current key, but parsed independently:

require('yargs-parser')('--foo bar', {
  coerce: {
    foo(value) {
      if (['true', 'false', 'maybe'].includes(value) return value
      this.doNotEat() // not currently defined; could also be an argument
      return 'maybe'
    }
  }
})
> { _: [ 'bar' ], foo: 'maybe' }

Start with yargs-parser's boolean-option handling and review the related yargs/yargs#1599 discussion. Compare the current --foo bar behavior with the proposed choices and coerce approaches; done means a defined way to preserve the positional value while allowing boolean options to gain additional choices without a breaking CLI change.