feat: split demand() into demandCommand()/demandOption()

[bcoe]

Getting @lrlna's wonderful work on splitting demand() into demandCommand()/demandOption() over the finish line.

Everything is %99 of the way there, just addressing some final nits from @maxrimue and myself -- excited to try to get yargs down to a few less open issue.

TODO:

• add a few more tests, specifically one for [New] if a demand message is provided, gsub in “got” and “count” #438.

fixes #504, #431 follow up with #618

[bcoe]

@ljharb sorry this turned into a never ending yak shave! The demand() API was pretty all over the place, and it took quite a bit of refactoring to get things to where we wanted them.

Any ways, months overdue but I think this gets things to what you pushed us towards. Thanks @lrlna for the hard work 🎉

[ljharb]

Thanks to everybody :-) I look forward to consuming it once it's released.

[lrlna]

Thanks for finishing this off @bcoe ✨ ; it looks really good!!

[bcoe]

@ljharb @maxrimue @lrlna this is queued up to go out with the next latest release of yargs. I would love your help testing since 6.6.0 is a big one:

npm cache clear; npm i yargs@next

[lrlna]

@bcoe are you doing this one as a major though? Or with 6.6.0 ?

[bcoe]

@lrlna since we opted to keep the demand() method for the time being, I see no reason to bump a major; however, I'm starting to picture what a 7.x release would look like. I would love to solve these problems specifically:

• alert when you're off the rails of the API: Silent crash when calling alias with only one parameter. #739
• don't catch program errors: Sync error of handler should throw a global error #455
• do some more work around whether options are applied globally.

CC: @nexdrew, @maxrimue

[maxrimue]

@bcoe I think that sounds like a good plan. What do you think when should we take action about the readme refactoring?

[bcoe]

@maxrimue I approve of this message; I've noticed a lot of big JS projects have moved towards smaller READMEs with external doc sites.

[bcoe]

@maxrimue want to start pulling together a v7 thread? I loved how you helped with release management last time.

[maxrimue]

@bcoe on it

[kumar303]

As of 6.6.0, demand() did slightly regress. The custom message is no longer displayed. That's ok though -- our tests failed, we read the readme, learned about the deprecation, and switched to the new methods :) Thanks for keeping a concise changelog.

[bcoe]

@kumar303 mind sharing the syntax that had a regression for you, I'd like to patch this in the 6.x stream.

[kumar303]

Sure, here is a script to reproduce it:

var yargs = require('yargs');
yargs
  .help('help')
  .demand(0, 0, 'This is a custom message to explain the error better')
  .strict()
  .argv;

In yargs@6.6.0:

$ node script.js nope
Options:
  --help  Show help                                                    [boolean]

Too many non-option arguments: got 1, maximum of 0

In yargs@6.5.0:

$ node script.js nope
Options:
  --help  Show help                                                    [boolean]

This is a custom message to explain the error better

[bcoe]

@kumar303 thank you; I'll get a regression test written this evening.