util: add parseArgs module

[bcoe]

Adds util.parseArgs helper for higher level command-line argument parsing.

---

Background

There has been an ongoing effort in pkgjs/parseargs to define a command-line argument parsing API for Node.js core.

The effort has taken several years to get to this point, with many amazing contributors across a variety of companies and projects: IBM, Microsoft, Google, Shopify, npm, nvm, commander, yargs, just to name a few.

Where parseArgs is at

@shadowspawn, who's been most recently pushing a lot of the work on parseArgs forward, indicates in pkgjs/parseargs/issues/87 that "we're close to having a decent MVP."

I agree, and thought it would be worth having a candidate PR open on Node.js to get additional feedback.

This is a controversial topic, be kind

There's a lot of nuance and opinion, as to what constitutes a "decent MVP" for a command-line argument parser. Please be respectful of opinions you might not agree with 😊

Before leaving feedback on this thread, I suggest reading past issues on parseArgs. Perhaps there's already been a discussion that touches on your feedback (or there's an ongoing discussion).

Similarly, if themes of discussion jump out in this PR, let's move them to an issue in parseArgs (this should help keep this PR less confusing).

ToDo

• PR: should flags be removed consolidating on values.~ landed
• PR: strict mode handling. landed
• Issue: should poisitional parsing be opt-in.
• finish audit of prototype pollution.

CC: @ljharb, @bakkot, @iansu, @darcyclarke, @ruyadorno, @shadowspawn, @nodejs/tooling, @Trott (who I believe asked after this), @aaronccasanova.

[nodejs-github-bot]

Review requested:

• @nodejs/startup

[mcollina]

I would recommend this to be exposed as node:parseargs instead (or analog in the node: prefix). process is already overloaded with so much functionality, I would prefer not adding new things there that could stay separate.

[ljharb]

It definitely should not be exposed only under the prefix, for a ton of reasons (but that’s being discussed elsewhere)

[bcoe]

I would recommend this to be exposed as node:parseargs

@mcollina done, opted for node:parse_args.

[bnb]

I am -1 on it being exposed only under the node: prefix. I do not much mind what it's called, but I'd strongly prefer that we do not limit new additions to that unless we're willing to fully break and force it for all modules, retroactively, and force all core modules under it.

I am, however, +1 on this landing assuming we can come to consensus on it.

[aaronccasanova]

My assumption thus far was that parseArgs would be exposed from the util module. However, I can see process.parseArgs() being a common replacement for process.argv and I think it would feel very intuitive for folks. That being said, I have no strong preference and would be happy with any consensus.

[cjihrig]

Left a few comments.

Regarding the node: scheme - there is a vote on this in nodejs/TSC#1206, which is expected to be completed Monday (so a decision can be made in time for Node 18). I think the outcome there should dictate how this module is exposed.

[bcoe]

I am -1 on it being exposed only under the node: prefix. I do not much mind what it's called, but I'd strongly prefer that we do not limit new additions to that unless we're willing to fully break and force it for all modules

@cjihrig @mcollina @bnb, can we agree that we will have the functionality available in node:parse_args, this would allow us to get this PR to an MVP with this assumption -- and if we then decide to also expose the feature in process or util, it's a non breaking addition.

[mcollina]

I'm totally ok for it to stay inside util, I'm just not ok with using process.

[bcoe]

@cjihrig @mcollina @Trott how would folks feel about this feature experimental in docs only? with strong warnings in the documentation that this is a work in progress?

On one hand, a runtime experimental warning makes it difficult to create real-world command line applications, as they'll have noisy output.

On the other hand, users might not realize it's experimental and get frustrated if the API breaks.

[mcollina]

I'm ok in being doc-only experimental.

[Trott]

@cjihrig @mcollina @Trott how would folks feel about this feature experimental in docs only? which strong warnings in the documentation that this is a work in progress?

I'd punt that to @nodejs/tsc and @nodejs/releasers. I'm personally fine with it, but I also wouldn't want that to sneak by anyone.

I'm not sure if this is actually feasible, but maybe we can split the difference and have a warning be emitted (so if anything is listening for warnings, it picks it up) but ignored by the default "print the warning to the console" listener.

[cjihrig]

would folks feel about this feature experimental in docs only?

I don't mind due to the nature of this API.

[bcoe]

@nodejs/tsc two questions I would love feedback on from the TSC:

1. would it be okay to expose this feature as util.parseArgs, as well as in the module node:parse_args?
2. would it be okay to indicate that this feature is experimental in docs only (which would make it easier for people to test the API for real world applications), or should it have a runtime experimental warning.

[RaisinTen]

1. would it be okay to expose this feature as util.parseArgs, as well as in the module node:parse_args?

I think it's okay to expose this as a part of the util module. It probably doesn't require a completely new module of its own because it's just a single function.

2. would it be okay to indicate that this feature is experimental in docs only (which would make it easier for people to test the API for real world applications), or should it have a runtime experimental warning.

I'm okay with it.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/44139/

[bcoe]

Fixes pkgjs/parseargs#109

[Trott]

I think this is ready to land, but it could use one more approval or re-approval since changes have been made since the last approval (and the commit queue won't merge something in that case). I'll rubber-stamp re-approve if no one wants to give it a proper review, but hopefully someone would like to look at it one more time?

[mcollina]

lgtm

[nodejs-github-bot]

Landed in 4a3ba87