util: add tokens to parseArgs #43459

shadowspawn · 2022-06-17T11:04:54Z

Offer additional meta-data for building custom and additional behaviour on top of parseArgs.

parseArgs supports the primary goal of a useful CLI parser for direct use, but is not offering much for the secondary goal of a basis for building richer functionality, or for customising the behaviour.

@bakkot proposed returning additional meta-data, such as reporting indexes. We have developed that idea into optionally returning a tokens structure with parsing meta-data in pkgjs/parseargs#129 with input from @aaronccasanova, @bcoe, and @ljharb.

The returned fields are a pragmatic mix of information useful to an author for custom behaviours or fancy error messages. The tokens are used internally by parseArgs for generating the returned values and positionals and performing error detection, using the same meta-data now available to callers. The downstream PR includes some example files of add-on processing: pkgjs/parseargs#129

Edit: fixed link to downstream PR.

bakkot · 2022-06-17T15:05:26Z

The point of this design is that it lets script authors do stuff like support --no-foo properties or stopping at the first positional argument (so you can build an API like npm or node). And it accomplishes this without needing parseArgs to explicitly support all that stuff - script authors can build more advanced functionality on top of tokens in a pretty straightforward way.

One thing none of us were particularly happy with: we wanted a way to indicate whether a given option was --long or -l style, and the way that we've done that is with a field called rawName which holds "--long" or "-l". (Assuming l is an alias for long, the name field of the token will hold "long" in either case.) rawName is maybe a little misleading because if you have something like -xy you'll get two tokens which have rawNames "-x" and "-y" respectively, even though -y never appeared literally in the input.

If anyone has a better idea how to represent this, please suggest it.

bricss · 2022-06-18T11:30:24Z

Sold! 🔨 Lets merge it 🤠 coz that's exactly 🎯 what we need 👀

shadowspawn · 2022-06-20T07:50:22Z

Example uses of tokens in parseArgs itself are the strict mode error detection for:

unknown options
"string" options used without an option-argument
"boolean" options used with an option-argument
option-argument ambiguous as looks like an option (this was not feasible for client to reproduce before tokens)
unexpected positional

And populating the returned values and positionals.

Example custom client uses of tokens in downstream PR:

implement negatable options, like --no-foo
error if option used more than once
enforce option order, like --experimental before --unstable-x
restricting long options to using equals (--foo=bar allows, --foo bar produces error)

None of these custom client cases were previously possible without client doing some parsing of inputs args themselves.

bcoe · 2022-06-20T18:36:51Z

@shadowspawn thanks for opening this PR 👏 will make an effort to give a through review soon.

bcoe

Left some initial review feedback.

bcoe · 2022-07-01T15:36:24Z

doc/api/util.md

+specifying `tokens: true` in the configuration. The returned tokens have
+properties describing:
+
+* all tokens


Just a thought, I would be tempted to make tokens a class rather than a POJO with a kind property:

class Token {} class OptionTerminator extends Token {} class PositionalToken extends Token {}

With the classes exposed on the parseArgs export:

const {Token, PositionalToken} = parseArgs

Then I think you could just document the tokens as classes, similar to Buffer.blob, nested under the top level parseArgs docs, similar to how the docs are laid out for the JavaScript embedder API.

Even if these are made classes they should definitely expose a kind property - it's really awkward to work with tree nodes which lack such a property, which is why pretty much every parser in the world has them. (Similarly, the DOM has nodeName in addition to nodes being instances of distinct classes.)

Even if these are made classes they should definitely expose a kind property

Sounds good to me. I think it might be worth the class based approach, so that people could opt to check instanceof, if they're so inclined?

Should we consider making kind a Symbol, or is a string preferable?

Strings are traditional - they're a lot easier to work with, since you don't have to import them.

Just a thought, I would be tempted to make tokens a class rather than a POJO

It did cross my mind as soon as I added the kind property. 😄 .

The examples of Blob and AsyncResource and AsyncLocalStorage are all objects that authors will create themselves, with methods and state, where I think a Class adds more value.

I'm not against classes as such, but not seeing benefits in this case.

My 2 cents is we should go with the first one and make it less verbose, the "existing" version can be a bit confusing I think. But feel free to disagree, none option is perfect anyway, and we can always edit the docs later if we find a better layout.

I definitely find the existing one massively clearer; muddling things up with unnecessary TS/Java-ish terms and structure makes things more confusing.

Mixed opinions straight away! Thanks both for feedback.

I will leave it as is, barring further feedback.

I like that we could map the interface based approach directly to the TypeScript types we release on DefinitelyTyped.

But I don't feel super strongly, and would rather not block progress on the API (as @aduh95 says, we can edit the docs later).

Reapproving this PR 👍, @aduh95 are you happy as is?

The compact POJO description is a bit subtle to read. How about an expanded version with all the properties listed?

Proposed expanded

A returned token has two properties which are always defined,
and some other properties which vary depending on the kind:

kind {string} One of 'option', 'positional', or 'option-terminator'.

index {number} Index of element in args containing token. So the
source argument for a token is args[token.index].

An option token has additional parse details
for an option detected in the input args:

kind = 'option'

index {number} Index of element in args containing token.

name {string} Long name of option.

rawName {string} How option used in args, like -f of --foo.

value {string | undefined} Option value specified in args.
Undefined for boolean options.

inlineValue {boolean | undefined} Whether option value specified inline,
like --foo=bar.

A positional token has just one additional property with the positional value:

kind = 'positional'

index {number} Index of element in args containing token.

value {string} The value of the positional argument in args (i.e. args[index]).

An option-terminator token has only the base properties:

kind = 'option-terminator'

index {number} Index of element in args containing token.

Old compact

The returned tokens have properties describing:

all tokens

kind {string} One of 'option', 'positional', or 'option-terminator'.

index {number} Index of element in args containing token. So the
source argument for a token is args[token.index].

option tokens

name {string} Long name of option.

rawName {string} How option used in args, like -f of --foo.

value {string | undefined} Option value specified in args.
Undefined for boolean options.

inlineValue {boolean | undefined} Whether option value specified inline,
like --foo=bar.

positional tokens

value {string} The value of the positional argument in args (i.e. args[index]).

option-terminator token

(Duplicate post of: pkgjs/parseargs#129 (comment))

doc/api/util.md

test/parallel/test-parse-args.mjs

doc/api/util.md

bcoe · 2022-07-01T15:50:21Z

CC: @aduh95, @cjihrig, @ruyadorno, who provided review for the first parseArgs PR.

doc/api/util.md

lib/internal/util/parse_args/parse_args.js

aduh95

We would need to add an entry to the YAML comment to document the history of the API.

shadowspawn · 2022-07-05T10:07:01Z

Added a changelog entry to the YAML.

doc/api/util.md

bcoe

I like the negate example 👌good demonstration of how this can be leveraged.

I'm fine with the POJO for tokens, but feels like we could figure out slightly better markdown syntax for describing the hierarchical relationship between tokens -- not a blocker for me.

Perhaps @Trott has some thoughts, who I believe has put a lot of work into making the reference docs top notch.

Trott · 2022-07-10T00:34:25Z

Perhaps @Trott has some thoughts, who I believe has put a lot of work into making the reference docs top notch.

I'm afraid that's not an aspect of things I've put a lot of thought to before and I don't have much to add to what you, @aduh95, and others have already said.

Offer additional meta-data for building custom and additional behaviour on top of parseArgs.

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

nodejs-github-bot · 2022-07-16T22:06:39Z

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

bcoe · 2022-07-18T15:14:07Z

Tests are green, @aduh95 are you happy to merge? with the understanding we're likely to iterate more on docs over time.

nodejs-github-bot · 2022-07-18T17:36:31Z

Landed in d0dbb75

Offer additional meta-data for building custom and additional behaviour on top of parseArgs. PR-URL: #43459 Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Notable changes: * doc: * add F3n67u to collaborators (Feng Yu) #43953 * deprecate coercion to integer in process.exit (Daeyeon Jeong) #43738 * (SEMVER-MINOR) deprecate diagnostics_channel object subscribe method (Stephen Belanger) #42714 * events: * (SEMVER-MINOR) expose CustomEvent on global with CLI flag (Daeyeon Jeong) #43885 * (SEMVER-MINOR) add `CustomEvent` (Daeyeon Jeong) #43514 * http: * (SEMVER-MINOR) add drop request event for http server (theanarkh) #43806 * lib: * (SEMVER-MINOR) improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) #42714 * util: * (SEMVER-MINOR) add tokens to parseArgs (John Gee) #43459

Notable changes: * doc: * add F3n67u to collaborators (Feng Yu)#43953 * deprecate coercion to integer in process.exit (Daeyeon Jeong) #43738 * (SEMVER-MINOR) deprecate diagnostics_channel object subscribe method (Stephen Belanger) #42714 * events: * (SEMVER-MINOR) expose CustomEvent on global with CLI flag (Daeyeon Jeong) #43885 * (SEMVER-MINOR) add `CustomEvent` (Daeyeon Jeong) #43514 * http: * (SEMVER-MINOR) add drop request event for http server (theanarkh) #43806 * lib: * (SEMVER-MINOR) improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) #42714 * util: * (SEMVER-MINOR) add tokens to parseArgs (John Gee) #43459 PR-URL: #43993

Notable changes: * doc: * add F3n67u to collaborators (Feng Yu) #43953 * deprecate coercion to integer in process.exit (Daeyeon Jeong) #43738 * (SEMVER-MINOR) deprecate diagnostics_channel object subscribe method (Stephen Belanger) #42714 * events: * (SEMVER-MINOR) expose CustomEvent on global with CLI flag (Daeyeon Jeong) #43885 * (SEMVER-MINOR) add `CustomEvent` (Daeyeon Jeong) #43514 * http: * (SEMVER-MINOR) add drop request event for http server (theanarkh) #43806 * lib: * (SEMVER-MINOR) improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) #42714 * util: * (SEMVER-MINOR) add tokens to parseArgs (John Gee) #43459 PR-URL: #43993

Offer additional meta-data for building custom and additional behaviour on top of parseArgs. PR-URL: #43459 Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

@kuriyosh

Notable changes: crypto: * (SEMVER-MINOR) remove Node.js-specific webcrypto extensions (Filip Skokan) #43310 * (SEMVER-MINOR) add CFRG curves to Web Crypto API (Filip Skokan) #42507 * (SEMVER-MINOR) make authTagLength optional for CC20P1305 (Tobias Nießen) #42427 * (SEMVER-MINOR) align webcrypto RSA key import/export with other implementations (Filip Skokan) #42816 deps: * update undici to 5.4.0 (Node.js GitHub Bot) #43262 * update undici to 5.3.0 (Node.js GitHub Bot) #43197 dns: * (SEMVER-MINOR) export error code constants from `dns/promises` (Feng Yu) #43176 doc: * add F3n67u to collaborators (Feng Yu) #43953 * deprecate coercion to integer in process.exit (Daeyeon Jeong) #43738 * (SEMVER-MINOR) deprecate diagnostics_channel object subscribe method (Stephen Belanger) #42714 * add LiviaMedeiros to collaborators (LiviaMedeiros) #43039 * add @kuriyosh to collaborators (Yoshiki Kurihara) #42824 * add RafaelGSS to collaborators (RafaelGSS) #42718 * add @meixg to collaborators (Xuguang Mei) #42576 errors: * (SEMVER-MINOR) add support for cause in aborterror (James M Snell) #41008 esm: * (SEMVER-MINOR) add chaining to loaders (Jacob Smith) #42623 events: * (SEMVER-MINOR) expose CustomEvent on global with CLI flag (Daeyeon Jeong) #43885 * (SEMVER-MINOR) add `CustomEvent` (Daeyeon Jeong) #43514 * (SEMVER-MINOR) propagate abortsignal reason in new AbortError ctor in events (James M Snell) #41008 fs: * (SEMVER-MINOR) propagate abortsignal reason in new AbortSignal constructors (James M Snell) #41008 * (SEMVER-MINOR) make params in writing methods optional (LiviaMedeiros) #42601 * (SEMVER-MINOR) add `read(buffer[, options])` versions (LiviaMedeiros) #42768 http: * (SEMVER-MINOR) add drop request event for http server (theanarkh) #43806 * (SEMVER-MINOR) add diagnostics channel for http client (theanarkh) #43580 * (SEMVER-MINOR) add perf_hooks detail for http request and client (theanarkh) #43361 * (SEMVER-MINOR) add uniqueHeaders option to request and createServer (Paolo Insogna) #41397 http2: * (SEMVER-MINOR) propagate abortsignal reason in new AbortError constructor (James M Snell) #41008 * (SEMVER-MINOR) compat support for array headers (OneNail) #42901 lib: * (SEMVER-MINOR) propagate abortsignal reason in new AbortError constructor in blob (James M Snell) #41008 * (SEMVER-MINOR) add abortSignal.throwIfAborted() (James M Snell) #40951 * (SEMVER-MINOR) improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) #42714 module: * (SEMVER-MINOR) add isBuiltIn method (hemanth.hm) #43396 module,repl: * (SEMVER-MINOR) support 'node:'-only core modules (Colin Ihrig) #42325 net: * (SEMVER-MINOR) add drop event for net server (theanarkh) #43582 * (SEMVER-MINOR) add ability to reset a tcp socket (pupilTong) #43112 node-api: * (SEMVER-MINOR) emit uncaught-exception on unhandled tsfn callbacks (Chengzhong Wu) #36510 perf_hooks: * (SEMVER-MINOR) add PerformanceResourceTiming (RafaelGSS) #42725 report: * (SEMVER-MINOR) add more heap infos in process report (theanarkh) #43116 src: * (SEMVER-MINOR) add --openssl-legacy-provider option (Daniel Bevenius) #40478 * (SEMVER-MINOR) define fs.constants.S_IWUSR & S_IRUSR for Win (Liviu Ionescu) #42757 src,doc,test: * (SEMVER-MAJOR) add --openssl-shared-config option (Daniel Bevenius) #43124 stream: * (SEMVER-MINOR) use cause options in AbortError constructors (James M Snell) #41008 * (SEMVER-MINOR) add iterator helper find (Nitzan Uziely) #41849 * (SEMVER-MINOR) add writableAborted (Robert Nagy) #40802 test: * (SEMVER-MINOR) add initial test module (Colin Ihrig) #42325 test_runner: * (SEMVER-MINOR) expose `describe` and `it` (Moshe Atlow) #43420 * (SEMVER-MINOR) add initial CLI runner (Colin Ihrig) #42658 * (SEMVER-MINOR) support 'only' tests (Colin Ihrig) #42514 timers: * (SEMVER-MINOR) propagate signal.reason in awaitable timers (James M Snell) #41008 util: * (SEMVER-MINOR) add tokens to parseArgs (John Gee) #43459 * (SEMVER-MINOR) add parseArgs module (Benjamin Coe) #42675 v8: * (SEMVER-MINOR) add v8.startupSnapshot utils (Joyee Cheung) #43329 * (SEMVER-MINOR) export more fields in getHeapStatistics (theanarkh) #42784 worker: * (SEMVER-MINOR) add hasRef() to MessagePort (Darshan Sen) #42849 PR-URL: TODO

##### [\`v18.7.0\`](https://github.com/nodejs/node/releases/tag/v18.7.0) ##### Notable changes - **doc**: - add F3n67u to collaborators (Feng Yu) [#43953](nodejs/node#43953) - deprecate coercion to integer in process.exit (Daeyeon Jeong) [#43738](nodejs/node#43738) - **(SEMVER-MINOR)** deprecate diagnostics_channel object subscribe method (Stephen Belanger) [#42714](nodejs/node#42714) - **events**: - **(SEMVER-MINOR)** expose CustomEvent on global with CLI flag (Daeyeon Jeong) [#43885](nodejs/node#43885) - **(SEMVER-MINOR)** add `CustomEvent` (Daeyeon Jeong) [#43514](nodejs/node#43514) - **http**: - **(SEMVER-MINOR)** add drop request event for http server (theanarkh) [#43806](nodejs/node#43806) - **lib**: - **(SEMVER-MINOR)** improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) [#42714](nodejs/node#42714) - **util**: - **(SEMVER-MINOR)** add tokens to parseArgs (John Gee) [#43459](nodejs/node#43459) ##### Commits - \[[`0aa255ab72`](nodejs/node@0aa255ab72)] - **bootstrap**: handle snapshot errors gracefully (Joyee Cheung) [#43531](nodejs/node#43531) - \[[`0783ddf57e`](nodejs/node@0783ddf57e)] - **buffer**: do not leak memory if buffer is too big (Keyhan Vakil) [#43938](nodejs/node#43938) - \[[`12657accdd`](nodejs/node@12657accdd)] - **build**: add .gitattributes for npm and other shims (Hrishikesh Kadam) [#43879](nodejs/node#43879) - \[[`c2db4f4581`](nodejs/node@c2db4f4581)] - **build**: make GitPod less noisy (Rich Trott) [#43829](nodejs/node#43829) - \[[`364deeadcd`](nodejs/node@364deeadcd)] - **build**: add GitHub token permissions for workflows (Varun Sharma) [#43743](nodejs/node#43743) - \[[`8b83b4d5be`](nodejs/node@8b83b4d5be)] - **child_process**: do not need to count length when maxBuffer is Infinity (theanarkh) [#43822](nodejs/node#43822) - \[[`c1893b7a7c`](nodejs/node@c1893b7a7c)] - **child_process**: avoid repeated calls to `normalizeSpawnArguments` (木杉) [#43345](nodejs/node#43345) - \[[`7b276b89b9`](nodejs/node@7b276b89b9)] - **cluster**: send connection to other server when worker drop it (theanarkh) [#43747](nodejs/node#43747) - \[[`e8c66f92a5`](nodejs/node@e8c66f92a5)] - **crypto**: remove unneeded guard (Rich Trott) [#43856](nodejs/node#43856) - \[[`c95132e9ea`](nodejs/node@c95132e9ea)] - **deps**: cherry-pick [libuv/libuv@`3a7b955`](libuv/libuv@3a7b955) (Ben Noordhuis) [#43950](nodejs/node#43950) - \[[`cc8d5426d2`](nodejs/node@cc8d5426d2)] - **deps**: cherry-pick [libuv/libuv@`abb109f`](libuv/libuv@abb109f) (Ben Noordhuis) [#43950](nodejs/node#43950) - \[[`7762e463d6`](nodejs/node@7762e463d6)] - **deps**: update corepack to 0.12.1 (Node.js GitHub Bot) [#43965](nodejs/node#43965) - \[[`1256c4dad5`](nodejs/node@1256c4dad5)] - **deps**: update hast-util-raw (Moshe Atlow) [#43927](nodejs/node#43927) - \[[`aac97c2d2a`](nodejs/node@aac97c2d2a)] - **deps**: update undici to 5.8.0 (Node.js GitHub Bot) [#43886](nodejs/node#43886) - \[[`cdff61917d`](nodejs/node@cdff61917d)] - **deps**: clean archs files for OpenSSL (RafaelGSS) [#43735](nodejs/node#43735) - \[[`fc936a84e4`](nodejs/node@fc936a84e4)] - **deps**: remove not used architectures (RafaelGSS) [#43735](nodejs/node#43735) - \[[`361a643d8b`](nodejs/node@361a643d8b)] - **deps**: V8: backport [`f3cad8c`](nodejs/node@f3cad8cec656) (Joyee Cheung) [#43531](nodejs/node#43531) - \[[`2e1732ebd0`](nodejs/node@2e1732ebd0)] - **deps**: V8: backport [`22698d2`](nodejs/node@22698d267667) (Chengzhong Wu) [#43751](nodejs/node#43751) - \[[`979f469d3a`](nodejs/node@979f469d3a)] - **deps**: upgrade npm to 8.15.0 (npm team) [#43917](nodejs/node#43917) - \[[`4096d81988`](nodejs/node@4096d81988)] - **deps**: upgrade npm to 8.14.0 (npm team) [#43826](nodejs/node#43826) - \[[`2ec8092e2c`](nodejs/node@2ec8092e2c)] - **deps,src**: use SIMD for normal base64 encoding (Brian White) [#39775](nodejs/node#39775) - \[[`67b4edde37`](nodejs/node@67b4edde37)] - **dns**: fix getServers return undefined (jiahao.si) [#43922](nodejs/node#43922) - \[[`7c75539a88`](nodejs/node@7c75539a88)] - **dns**: fix cares memory leak (theanarkh) [#43912](nodejs/node#43912) - \[[`1f80b88da5`](nodejs/node@1f80b88da5)] - **doc**: update email and mailmap for BethGriggs (Beth Griggs) [#43985](nodejs/node#43985) - \[[`8a2a6e16eb`](nodejs/node@8a2a6e16eb)] - **doc**: add 15.x - 18.x to Other Versions section (shhh7612) [#43940](nodejs/node#43940) - \[[`51cb0d42ca`](nodejs/node@51cb0d42ca)] - **doc**: inspector.close undefined in worker threads (Keyhan Vakil) [#43867](nodejs/node#43867) - \[[`c789c0f5f7`](nodejs/node@c789c0f5f7)] - **doc**: improve documentation for safe `Promise` statics alternatives (Antoine du Hamel) [#43759](nodejs/node#43759) - \[[`cb9b0e0011`](nodejs/node@cb9b0e0011)] - **doc**: recommend git-node-v8 (Keyhan Vakil) [#43934](nodejs/node#43934) - \[[`d7e9bd1830`](nodejs/node@d7e9bd1830)] - **doc**: clarify subprocess.stdout/in/err property (Kohei Ueno) [#43910](nodejs/node#43910) - \[[`808793ebb5`](nodejs/node@808793ebb5)] - **doc**: fix typo in `src/crypto/README.md` (Jianru Lin) [#43968](nodejs/node#43968) - \[[`bbc455c4f9`](nodejs/node@bbc455c4f9)] - **doc**: remind backporter about v8\_embedder_string (Keyhan Vakil) [#43924](nodejs/node#43924) - \[[`a86b66c8b4`](nodejs/node@a86b66c8b4)] - **doc**: fix typo in http.md (Airing) [#43933](nodejs/node#43933) - \[[`a96af37233`](nodejs/node@a96af37233)] - **doc**: add F3n67u to collaborators (Feng Yu) [#43953](nodejs/node#43953) - \[[`aa7d4e59f7`](nodejs/node@aa7d4e59f7)] - **doc**: improve test runner timeout docs (Tobias Nießen) [#43836](nodejs/node#43836) - \[[`80c2fa8212`](nodejs/node@80c2fa8212)] - **doc**: mention Win 32-bit openssl build issue (RafaelGSS) [#43853](nodejs/node#43853) - \[[`8b8c55df7e`](nodejs/node@8b8c55df7e)] - **doc**: add security release specifics to releases.md (Beth Griggs) [#43835](nodejs/node#43835) - \[[`42693aaf9f`](nodejs/node@42693aaf9f)] - **doc**: add history info for `global.performance` (Antoine du Hamel) [#43841](nodejs/node#43841) - \[[`140d6af572`](nodejs/node@140d6af572)] - **doc**: add platform-windows-arm to who to CC (Michael Dawson) [#43808](nodejs/node#43808) - \[[`976093efe3`](nodejs/node@976093efe3)] - **doc**: document ES2022's Error "cause" property (James Ide) [#43830](nodejs/node#43830) - \[[`ec7e45e4a2`](nodejs/node@ec7e45e4a2)] - **doc**: include make clean to openssl arch (RafaelGSS) [#43735](nodejs/node#43735) - \[[`d64dfd53c9`](nodejs/node@d64dfd53c9)] - **doc**: add link to diagnostic tools (Rafael Gonzaga) [#43736](nodejs/node#43736) - \[[`2910136920`](nodejs/node@2910136920)] - **doc**: update links to MDN page about dynamic imports (Jannis R) [#43847](nodejs/node#43847) - \[[`d88a9fae79`](nodejs/node@d88a9fae79)] - **doc**: deprecate coercion to integer in process.exit (Daeyeon Jeong) [#43738](nodejs/node#43738) - \[[`fc843e103d`](nodejs/node@fc843e103d)] - **doc**: add MoLow to triagers (Moshe Atlow) [#43799](nodejs/node#43799) - \[[`8c8c97da61`](nodejs/node@8c8c97da61)] - **(SEMVER-MINOR)** **doc**: deprecate diagnostics_channel object subscribe method (Stephen Belanger) [#42714](nodejs/node#42714) - \[[`9b53a694b5`](nodejs/node@9b53a694b5)] - **doc**: revert anachronistic 'node:' module require()s in API history notes (DeeDeeG) [#43768](nodejs/node#43768) - \[[`2815bd3002`](nodejs/node@2815bd3002)] - **doc**: clarify release process for new releasers (Rafael Gonzaga) [#43739](nodejs/node#43739) - \[[`50b3750e67`](nodejs/node@50b3750e67)] - **doc**: fix typo in ngtcp2 readme (Dan Castillo) [#43767](nodejs/node#43767) - \[[`6bcd40dd85`](nodejs/node@6bcd40dd85)] - **domain**: fix vm promise tracking while keeping isolation (Stephen Belanger) [#43556](nodejs/node#43556) - \[[`e89e0b470b`](nodejs/node@e89e0b470b)] - **esm**: remove superfluous argument (Rich Trott) [#43884](nodejs/node#43884) - \[[`0d2921f396`](nodejs/node@0d2921f396)] - **esm**: fix erroneous re-initialization of ESMLoader (Jacob Smith) [#43763](nodejs/node#43763) - \[[`9b5b8d78c3`](nodejs/node@9b5b8d78c3)] - **esm**: throw on any non-2xx response (LiviaMedeiros) [#43742](nodejs/node#43742) - \[[`dfc4832ef1`](nodejs/node@dfc4832ef1)] - **(SEMVER-MINOR)** **events**: expose CustomEvent on global with CLI flag (Daeyeon Jeong) [#43885](nodejs/node#43885) - \[[`e4473952ae`](nodejs/node@e4473952ae)] - **(SEMVER-MINOR)** **events**: add `CustomEvent` (Daeyeon Jeong) [#43514](nodejs/node#43514) - \[[`100f6deb09`](nodejs/node@100f6deb09)] - **fs**: use signed types for stat data (LiviaMedeiros) [#43714](nodejs/node#43714) - \[[`25ec71db63`](nodejs/node@25ec71db63)] - **http**: fix http server connection list when close (theanarkh) [#43949](nodejs/node#43949) - \[[`ca658c8afe`](nodejs/node@ca658c8afe)] - **(SEMVER-MINOR)** **http**: add drop request event for http server (theanarkh) [#43806](nodejs/node#43806) - \[[`9c699bd8a8`](nodejs/node@9c699bd8a8)] - **http**: wait for pending responses in closeIdleConnections (Paolo Insogna) [#43890](nodejs/node#43890) - \[[`781d5e54e3`](nodejs/node@781d5e54e3)] - **inspector**: set sampling interval before start (Shelley Vohr) [#43779](nodejs/node#43779) - \[[`0b5dbb2a56`](nodejs/node@0b5dbb2a56)] - **lib**: refactor PriorityQueue to use private field (Finn Yu) [#43889](nodejs/node#43889) - \[[`324473ca32`](nodejs/node@324473ca32)] - **(SEMVER-MINOR)** **lib**: improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) [#42714](nodejs/node#42714) - \[[`5aa3b213ac`](nodejs/node@5aa3b213ac)] - **meta**: update AUTHORS (Node.js GitHub Bot) [#43966](nodejs/node#43966) - \[[`e707552357`](nodejs/node@e707552357)] - **meta**: update `node-api` in label-pr-config (Daeyeon Jeong) [#43794](nodejs/node#43794) - \[[`8a8de94034`](nodejs/node@8a8de94034)] - **meta**: update AUTHORS (Node.js GitHub Bot) [#43872](nodejs/node#43872) - \[[`7d49fc766c`](nodejs/node@7d49fc766c)] - **meta**: use platform dropdown on flaky template (Rafael Gonzaga) [#43855](nodejs/node#43855) - \[[`e4aa50fc3f`](nodejs/node@e4aa50fc3f)] - **meta**: enable blank issues (Matteo Collina) [#43775](nodejs/node#43775) - \[[`ceb7c150ec`](nodejs/node@ceb7c150ec)] - **meta**: move one or more collaborators to emeritus (Node.js GitHub Bot) [#43770](nodejs/node#43770) - \[[`29bcd47738`](nodejs/node@29bcd47738)] - **net**: fix socket.\_getpeername (Daeyeon Jeong) [#43010](nodejs/node#43010) - \[[`380659daf1`](nodejs/node@380659daf1)] - **process**: use `defineProperty` instead of assignment (Mark S. Miller) [#43907](nodejs/node#43907) - \[[`aba9c8ebea`](nodejs/node@aba9c8ebea)] - **repl**: fix overzealous top-level await (Tobias Nießen) [#43827](nodejs/node#43827) - \[[`1deb6b73b7`](nodejs/node@1deb6b73b7)] - **repl**: use `SafePromiseAll` and `SafePromiseRace` (Antoine du Hamel) [#43758](nodejs/node#43758) - \[[`bf8f2e23ff`](nodejs/node@bf8f2e23ff)] - **src**: refactor DH groups to delete crypto_groups.h (Tobias Nießen) [#43896](nodejs/node#43896) - \[[`9435fbf8cd`](nodejs/node@9435fbf8cd)] - **src**: remove dead code in base64\_encode (Tobias Nießen) [#43979](nodejs/node#43979) - \[[`2c47e58ea0`](nodejs/node@2c47e58ea0)] - **src**: fix regression that a source marker is lost (cola119) [#43086](nodejs/node#43086) - \[[`d084150320`](nodejs/node@d084150320)] - **src**: per-isolate eternal template properties (Chengzhong Wu) [#43802](nodejs/node#43802) - \[[`9f9d00ccbb`](nodejs/node@9f9d00ccbb)] - **src**: merge NativeModuleEnv into NativeModuleLoader (Joyee Cheung) [#43824](nodejs/node#43824) - \[[`bb512904e9`](nodejs/node@bb512904e9)] - **src**: use named struct instead of typedef (Tobias Nießen) [#43881](nodejs/node#43881) - \[[`bb5511e8cc`](nodejs/node@bb5511e8cc)] - **src**: use named enum instead of typedef (Tobias Nießen) [#43880](nodejs/node#43880) - \[[`5db0c8f667`](nodejs/node@5db0c8f667)] - **src**: pass only Isolate\* and env_vars to EnabledDebugList::Parse() (Darshan Sen) [#43668](nodejs/node#43668) - \[[`249365524e`](nodejs/node@249365524e)] - **src**: fix node watchdog race condition (theanarkh) [#43780](nodejs/node#43780) - \[[`17cb27237d`](nodejs/node@17cb27237d)] - **src**: deduplicate `SetALPN` implementations (Tobias Nießen) [#43756](nodejs/node#43756) - \[[`b4c75a96be`](nodejs/node@b4c75a96be)] - **src**: fix `napi_check_object_type_tag()` (Daeyeon Jeong) [#43788](nodejs/node#43788) - \[[`8432d6596f`](nodejs/node@8432d6596f)] - **src**: slim down env-inl.h (Ben Noordhuis) [#43745](nodejs/node#43745) - \[[`2266a4b6d6`](nodejs/node@2266a4b6d6)] - **stream**: improve `respondWithNewView()` (Daeyeon Jeong) [#43866](nodejs/node#43866) - \[[`bf3991b406`](nodejs/node@bf3991b406)] - **stream**: fix 0 transform hwm backpressure (Robert Nagy) [#43685](nodejs/node#43685) - \[[`a057510037`](nodejs/node@a057510037)] - **stream**: initial approach to include strategy options on Readable.toWeb() (txxnano) [#43515](nodejs/node#43515) - \[[`198cf59d2c`](nodejs/node@198cf59d2c)] - **test**: update WPT encoding tests (Kohei Ueno) [#43958](nodejs/node#43958) - \[[`f0ed1aed8d`](nodejs/node@f0ed1aed8d)] - **test**: remove test-whatwg-events-add-event-listener-options-once.js (Feng Yu) [#43877](nodejs/node#43877) - \[[`88505556fe`](nodejs/node@88505556fe)] - **test**: work scheduled in process.nextTick can keep the event loop alive (Andreu Botella) [#43787](nodejs/node#43787) - \[[`81a21946eb`](nodejs/node@81a21946eb)] - **test**: simplify test-tls-set-secure-context (Tobias Nießen) [#43878](nodejs/node#43878) - \[[`61cd11a8a7`](nodejs/node@61cd11a8a7)] - **test**: use `common.mustNotMutateObjectDeep()` in fs tests (LiviaMedeiros) [#43819](nodejs/node#43819) - \[[`b1081dbe12`](nodejs/node@b1081dbe12)] - **test**: fix test http upload timeout (theanarkh) [#43935](nodejs/node#43935) - \[[`efd5e0e925`](nodejs/node@efd5e0e925)] - **test**: simplify ReplStream.wait() (Tobias Nießen) [#43857](nodejs/node#43857) - \[[`ef21ad2996`](nodejs/node@ef21ad2996)] - **test**: merge test-crypto-dh-hash with modp18 test (Tobias Nießen) [#43891](nodejs/node#43891) - \[[`e502c50a90`](nodejs/node@e502c50a90)] - **test**: refactor `test/es-module/test-esm-resolve-type` (Antoine du Hamel) [#43178](nodejs/node#43178) - \[[`c782c3dc69`](nodejs/node@c782c3dc69)] - **test**: ensure NODE_EXTRA_CA_CERTS not set before tests (KrayzeeKev) [#43858](nodejs/node#43858) - \[[`bb6787cb57`](nodejs/node@bb6787cb57)] - **test**: add check to test-fs-readfile-tostring-fail (Richard Lau) [#43850](nodejs/node#43850) - \[[`7571704186`](nodejs/node@7571704186)] - **test**: complete TODO in test/wpt/test-url.js (Kohei Ueno) [#43797](nodejs/node#43797) - \[[`6f1d2dfb9d`](nodejs/node@6f1d2dfb9d)] - **test**: add test on worker process.exit in async modules (Chengzhong Wu) [#43751](nodejs/node#43751) - \[[`776cc3abbd`](nodejs/node@776cc3abbd)] - **test**: use `common.mustNotMutateObjectDeep()` in immutability tests (LiviaMedeiros) [#43196](nodejs/node#43196) - \[[`42f2deb3a0`](nodejs/node@42f2deb3a0)] - **test**: add `common.mustNotMutateObjectDeep()` (LiviaMedeiros) [#43196](nodejs/node#43196) - \[[`f3fc51c508`](nodejs/node@f3fc51c508)] - **test**: fix coverity warning in test (Michael Dawson) [#43631](nodejs/node#43631) - \[[`a9ecba2fa8`](nodejs/node@a9ecba2fa8)] - **test**: mark test-http-client-response-timeout flaky (Tobias Nießen) [#43792](nodejs/node#43792) - \[[`cd0d9ddb7c`](nodejs/node@cd0d9ddb7c)] - **test_runner**: add support for boolean values for `concurrency` option (Lenvin Gonsalves) [#43887](nodejs/node#43887) - \[[`f98020138a`](nodejs/node@f98020138a)] - **test_runner**: validate `timeout` option (Antoine du Hamel) [#43843](nodejs/node#43843) - \[[`58d15b3687`](nodejs/node@58d15b3687)] - **test_runner**: pass signal on timeout (Moshe Atlow) [#43911](nodejs/node#43911) - \[[`8b0248506f`](nodejs/node@8b0248506f)] - **test_runner**: do not report an error when tests are passing (Antoine du Hamel) [#43919](nodejs/node#43919) - \[[`aa8053e1fa`](nodejs/node@aa8053e1fa)] - **test_runner**: recieve and pass AbortSignal (Moshe Atlow) [#43554](nodejs/node#43554) - \[[`f13e4c1be9`](nodejs/node@f13e4c1be9)] - **test_runner**: fix `it` concurrency (Moshe Atlow) [#43757](nodejs/node#43757) - \[[`e404a3ef6d`](nodejs/node@e404a3ef6d)] - **test_runner**: support timeout for tests (Moshe Atlow) [#43505](nodejs/node#43505) - \[[`f28198cc05`](nodejs/node@f28198cc05)] - **test_runner**: catch errors thrown within `describe` (Moshe Atlow) [#43729](nodejs/node#43729) - \[[`bfe0ac6cd0`](nodejs/node@bfe0ac6cd0)] - **tools**: add more options to track flaky tests (Antoine du Hamel) [#43954](nodejs/node#43954) - \[[`17a4e5e775`](nodejs/node@17a4e5e775)] - **tools**: add verbose flag to inactive TSC finder (Rich Trott) [#43913](nodejs/node#43913) - \[[`373304b0c7`](nodejs/node@373304b0c7)] - **tools**: add support for using API key to vuln checking script (Facundo Tuesca) [#43909](nodejs/node#43909) - \[[`ed45088c14`](nodejs/node@ed45088c14)] - **tools**: support versioned node shared libs on z/OS (alexcfyung) [#42256](nodejs/node#42256) - \[[`c9ecd6d21f`](nodejs/node@c9ecd6d21f)] - **tools**: update doc to highlight.js@11.6.0 (Node.js GitHub Bot) [#43870](nodejs/node#43870) - \[[`c92135aa0f`](nodejs/node@c92135aa0f)] - **tools**: update lint-md-dependencies to rollup@2.77.0 (Node.js GitHub Bot) [#43871](nodejs/node#43871) - \[[`e12bf40fd1`](nodejs/node@e12bf40fd1)] - **tools**: update eslint to 8.20.0 (Node.js GitHub Bot) [#43873](nodejs/node#43873) - \[[`09fe9b30a9`](nodejs/node@09fe9b30a9)] - **tools**: add script for vulnerability checking (Facundo Tuesca) [#43362](nodejs/node#43362) - \[[`19e8876877`](nodejs/node@19e8876877)] - **trace_events**: trace net connect event (theanarkh) [#43903](nodejs/node#43903) - \[[`1af7f24143`](nodejs/node@1af7f24143)] - **util**: remove unicode support todo for perf implications (Rhys) [#43762](nodejs/node#43762) - \[[`acfc33ca8c`](nodejs/node@acfc33ca8c)] - **(SEMVER-MINOR)** **util**: add tokens to parseArgs (John Gee) [#43459](nodejs/node#43459) - \[[`f32aec8a6d`](nodejs/node@f32aec8a6d)] - **util**: refactor to use validateObject (Kohei Ueno) [#43769](nodejs/node#43769) - \[[`d7cfd0c5ba`](nodejs/node@d7cfd0c5ba)] - **v8**: serialize BigInt64Array and BigUint64Array (Ben Noordhuis) [#43571](nodejs/node#43571)

Offer additional meta-data for building custom and additional behaviour on top of parseArgs. PR-URL: nodejs#43459 Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Notable changes: * doc: * add F3n67u to collaborators (Feng Yu) nodejs#43953 * deprecate coercion to integer in process.exit (Daeyeon Jeong) nodejs#43738 * (SEMVER-MINOR) deprecate diagnostics_channel object subscribe method (Stephen Belanger) nodejs#42714 * events: * (SEMVER-MINOR) expose CustomEvent on global with CLI flag (Daeyeon Jeong) nodejs#43885 * (SEMVER-MINOR) add `CustomEvent` (Daeyeon Jeong) nodejs#43514 * http: * (SEMVER-MINOR) add drop request event for http server (theanarkh) nodejs#43806 * lib: * (SEMVER-MINOR) improved diagnostics_channel subscribe/unsubscribe (Stephen Belanger) nodejs#42714 * util: * (SEMVER-MINOR) add tokens to parseArgs (John Gee) nodejs#43459 PR-URL: nodejs#43993

Offer additional meta-data for building custom and additional behaviour on top of parseArgs. PR-URL: nodejs/node#43459 Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

nodejs-github-bot added needs-ci PRs that need a full CI run. util Issues and PRs related to the built-in util module. labels Jun 17, 2022

bcoe suggested changes Jul 1, 2022

View reviewed changes

bakkot reviewed Jul 1, 2022

View reviewed changes

doc/api/util.md Outdated Show resolved Hide resolved

bakkot mentioned this pull request Jul 4, 2022

TypeScript types pkgjs/parseargs#127

Open

aduh95 reviewed Jul 5, 2022

View reviewed changes

lib/internal/util/parse_args/parse_args.js Outdated Show resolved Hide resolved

aduh95 reviewed Jul 5, 2022

View reviewed changes

aduh95 added the semver-minor PRs that contain new features and should be released in the next minor version. label Jul 5, 2022

This comment was marked as resolved.

Sign in to view

aduh95 reviewed Jul 5, 2022

View reviewed changes

doc/api/util.md Outdated Show resolved Hide resolved

doc/api/util.md Outdated Show resolved Hide resolved

doc/api/util.md Outdated Show resolved Hide resolved

doc/api/util.md Show resolved Hide resolved

doc/api/util.md Outdated Show resolved Hide resolved

bcoe approved these changes Jul 9, 2022

View reviewed changes

bcoe approved these changes Jul 13, 2022

View reviewed changes

This comment was marked as outdated.

Sign in to view

bcoe approved these changes Jul 13, 2022

View reviewed changes

This was referenced Jul 14, 2022

CI Reliability 2022-07-14 nodejs/reliability#322

Open

CI Reliability 2022-07-15 nodejs/reliability#323

Open

This comment was marked as outdated.

Sign in to view

shadowspawn and others added 6 commits July 16, 2022 10:26

util: add tokens to parseArgs

1060df0

Offer additional meta-data for building custom and additional behaviour on top of parseArgs.

Improve wording

ed54c30

Use negate as example for tokens. Rework description a little.

fb2cd00

Lint and feedback

2570047

Expand short token tests and remove unwieldy tests

33dbe57

Add suggested change

27d9e4d

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jul 16, 2022

shadowspawn mentioned this pull request Jul 16, 2022

feat: add parsed meta-data to returned properties pkgjs/parseargs#129

Merged

aduh95 approved these changes Jul 18, 2022

View reviewed changes

aduh95 added commit-queue Add this label to land a pull request using GitHub Actions. commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. labels Jul 18, 2022

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Jul 18, 2022

nodejs-github-bot merged commit d0dbb75 into nodejs:main Jul 18, 2022

github-actions bot mentioned this pull request Jul 19, 2022

CI Reliability 2022-07-19 nodejs/reliability#325

Open

19 tasks

shadowspawn deleted the parseargs-tokens branch July 22, 2022 07:58

danielleadams mentioned this pull request Jul 26, 2022

v18.7.0 proposal #43993

Merged

bakkot mentioned this pull request Jul 30, 2022

feat(node): types for util.parseArgs DefinitelyTyped/DefinitelyTyped#61512

Merged

8 tasks

targos mentioned this pull request Aug 2, 2022

v16.17.0 release proposal #44098

Merged

shadowspawn mentioned this pull request Sep 10, 2022

feat: add default option parameter pkgjs/parseargs#142

Merged

shadowspawn mentioned this pull request Aug 24, 2023

doc: refine sample code on tokens of util/parseArgs #49263

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

util: add tokens to parseArgs #43459

util: add tokens to parseArgs #43459

shadowspawn commented Jun 17, 2022 •

edited

bakkot commented Jun 17, 2022

bricss commented Jun 18, 2022 •

edited

shadowspawn commented Jun 20, 2022 •

edited

bcoe commented Jun 20, 2022

bcoe left a comment

bcoe Jul 1, 2022

bakkot Jul 1, 2022

bcoe Jul 1, 2022

bakkot Jul 1, 2022

shadowspawn Jul 1, 2022

aduh95 Jul 11, 2022

ljharb Jul 11, 2022

shadowspawn Jul 11, 2022

bcoe Jul 13, 2022

shadowspawn Jul 16, 2022

bcoe commented Jul 1, 2022

aduh95 left a comment •

edited

This comment was marked as resolved.

shadowspawn commented Jul 5, 2022

bcoe left a comment

Trott commented Jul 10, 2022

This comment was marked as outdated.

This comment was marked as outdated.

nodejs-github-bot commented Jul 16, 2022 •

edited by bcoe

bcoe commented Jul 18, 2022

nodejs-github-bot commented Jul 18, 2022

util: add tokens to parseArgs #43459

util: add tokens to parseArgs #43459

Conversation

shadowspawn commented Jun 17, 2022 • edited

bakkot commented Jun 17, 2022

bricss commented Jun 18, 2022 • edited

shadowspawn commented Jun 20, 2022 • edited

bcoe commented Jun 20, 2022

bcoe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Proposed expanded

Old compact

bcoe commented Jul 1, 2022

aduh95 left a comment • edited

Choose a reason for hiding this comment

This comment was marked as resolved.

shadowspawn commented Jul 5, 2022

bcoe left a comment

Choose a reason for hiding this comment

Trott commented Jul 10, 2022

This comment was marked as outdated.

This comment was marked as outdated.

nodejs-github-bot commented Jul 16, 2022 • edited by bcoe

bcoe commented Jul 18, 2022

nodejs-github-bot commented Jul 18, 2022

shadowspawn commented Jun 17, 2022 •

edited

bricss commented Jun 18, 2022 •

edited

shadowspawn commented Jun 20, 2022 •

edited

aduh95 left a comment •

edited

nodejs-github-bot commented Jul 16, 2022 •

edited by bcoe