Add support for getting merged options including globals

[shadowspawn]

Pull Request

Problem

Currently no direct support for getting merged options including globals. The work-around is to access the global options on the program or command parent.

This was the second most popular enhancement in poll #1551 (comment)

Related issues: #243 #476 (comment) #1024 #1229

Previous consideration by me: #1229 (comment) #1155 #1478

Solution

Add mergeOptions parameter to `.opts()`.

const options = cmd.opts();
const mergedOptions = cmd.opts({ includeGlobals: true });

Add command.optsWithGlobals().

Example Usage

const { program } = require('commander');

program
  .option('-g, --global');

program
  .command('sub')
  .option('-l, --local')
  .action((options, cmd) => {
    console.log({
      opts: cmd.opts(),
      optsWithGlobals: cmd.optsWithGlobals())
    });
  });

program.parse();

$ node index.js sub --global --local
{
  opts: { local: true },
  optsWithGlobals: { local: true, global: true }
}

ChangeLog

• add .optsWithGlobals() to return merged local and global options

[kuncevic]

Oh, BTW, why wouldn't { includeGlobals: true } became a default behavior?

[shadowspawn]

Option 2 in the poll was a configuration to always include the globals in the options, but it didn't get a lot of likes.

[kuncevic]

Yeah i c, in that case you had to call that program.includeGlobalsInOptions(); however you may want to pass more params to .opts({ includeGlobals: true, more_params }) right?

[shadowspawn]

Yes. Commander has some routines where the boolean arg is optional because the method name is clear about what will happen:

program
  .allowUnknownOption()
  .storeOptionsAsProperties();

I don't like adding a plain boolean parameter which has no obvious meaning, like say:

program.opts(true);

Adding an options parameter makes effect clearer by naming the value, especially when not commonly used, and also allows future expansion.

program.parse(['--debug'], { from: 'user' });
program.help({ error: true });
program.command('foo', 'foo description', { isDefault: true });

[kuncevic]

Yeah, plain boolean is definitely no go. However speakingprogram.includeGlobalsInOptions(); vs .opts({ includeGlobals: true }) as you already have things like .allowUnknownOption() having .includeGlobalsInOptions(); seems quite natural.

[shadowspawn]

Yes I agree .includeGlobalsInOptions() flows better than .opts({ includeGlobals: true }).

Using a separate method would look like:

//const mergedOptions = cmd.cmd.opts({ includeGlobals: true })
const mergedOptions = cmd.optsWithGlobals();

Do you like that better?

(Or are you now thinking option 2 is better!?)

[kuncevic]

Yeah, cmd.optsWithGlobals(); looks good, it seems more natural and really flows better along with .allowUnknownOption(), etc.

[shadowspawn]

Switched to .optsWithGlobals in PR description and code.

[kuncevic]

That is great. Looking forward to see it pushed in the next release 🔥

[abetomo]

LGTM!

[shadowspawn]

Thanks @kuncevic and @abetomo

[shadowspawn]

.optsWithGlobals() is included in prerelease Commander v9.0.0-1.

[shadowspawn]

Commander v9 has been released.