feat: add parsed meta-data to returned properties

.editorconfig

@@ -3,10 +3,12 @@
 # top-most EditorConfig file
 root = true
 
+# Copied from Node.js to ease compatibility in PR.
 [*]
+charset = utf-8
 end_of_line = lf
-insert_final_newline = true
-indent_style = space
 indent_size = 2
-tab_width = 2
-# trim_trailing_whitespace = true
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+quote_type = single

README.md

@@ -25,18 +25,24 @@ added: REPLACEME
       times. If `true`, all values will be collected in an array. If
       `false`, values for the option are last-wins. **Default:** `false`.
     * `short` {string} A single character alias for the option.
-  * `strict`: {boolean} Should an error be thrown when unknown arguments
+  * `strict` {boolean} Should an error be thrown when unknown arguments
     are encountered, or when arguments are passed that do not match the
     `type` configured in `options`.
     **Default:** `true`.
-  * `allowPositionals`: {boolean} Whether this command accepts positional
+  * `allowPositionals` {boolean} Whether this command accepts positional
     arguments.
     **Default:** `false` if `strict` is `true`, otherwise `true`.
+  * `tokens` {boolean} Return an array with the
+    parsed tokens. This is useful for extending the built-in behaviour,
+    from adding additional checks through to reprocessing the tokens
+    in different ways.
+    **Default:** `false`.
 
 * Returns: {Object} The parsed command line arguments:
   * `values` {Object} A mapping of parsed option names with their {string}
     or {boolean} values.
   * `positionals` {string\[]} Positional arguments.
+  * `tokens` {Object} Parsed tokens. Only present if requested.
 
 Provides a higher level API for command-line argument parsing than interacting
 with `process.argv` directly. Takes a specification for the expected arguments
@@ -79,10 +85,114 @@ const {
   positionals
 } = parseArgs({ args, options });
 console.log(values, positionals);
-// Prints: [Object: null prototype] { foo: true, bar: 'b' } []ss
+// Prints: [Object: null prototype] { foo: true, bar: 'b' } []
+```
+
+Detailed parse information is available for adding custom behaviours by
+specifying `tokens: true` in the configuration.
+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
+
+The returned tokens are in the order encountered in the input args. Options that appear
+more than once in args produce a token for each use.
+Short option groups like `-xy` expand to a token for each option. So `-xxx` produces
+three tokens.
+
+For example to use the returned tokens to add support for a negated option like `--no-color`, the tokens
+can be reprocessed to change the value stored for the negated option.
+
+```mjs
+import { parseArgs } from 'node:util';
+
+const options = {
+  ['color']: { type: 'boolean' },
+  ['no-color']: { type: 'boolean' },
+  ['logfile']: { type: 'string' },
+  ['no-logfile']: { type: 'boolean' },
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+// Reprocess the option tokens and overwrite the returned values.
+tokens
+  .filter((token) => token.kind === 'option')
+  .forEach((token) => {
+    if (token.name.startsWith('no-')) {
+      // Store foo:false for --no-foo
+      const positiveName = token.name.slice(3);
+      values[positiveName] = false;
+      delete values[token.name];
+    } else {
+      // Resave value so last one wins if both --foo and --no-foo.
+      values[token.name] = token.value ?? true;
+    }
+  });
+
+const color = values.color;
+const logfile = values.logfile ?? 'default.log';
+
+console.log({ logfile, color });
+```
+
+```cjs
+const { parseArgs } = require('node:util');
+
+const options = {
+  ['color']: { type: 'boolean' },
+  ['no-color']: { type: 'boolean' },
+  ['logfile']: { type: 'string' },
+  ['no-logfile']: { type: 'boolean' },
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+// Reprocess the option tokens and overwrite the returned values.
+tokens
+  .filter((token) => token.kind === 'option')
+  .forEach((token) => {
+    if (token.name.startsWith('no-')) {
+      // Store foo:false for --no-foo
+      const positiveName = token.name.slice(3);
+      values[positiveName] = false;
+      delete values[token.name];
+    } else {
+      // Resave value so last one wins if both --foo and --no-foo.
+      values[token.name] = token.value ?? true;
+    }
+  });
+
+const color = values.color;
+const logfile = values.logfile ?? 'default.log';
+
+console.log({ logfile, color });
+```
+
+Example usage showing negated options, and when option use multiple times then last one wins.
+
+```console
+$ node negate.js
+{ logfile: 'default.log', color: undefined }
+$ node negate.js --no-logfile --no-color
+{ logfile: false, color: false }
+$ node negate.js --logfile=test.log --color
+{ logfile: 'test.log', color: true }
+$ node negate.js --no-logfile --logfile=test.log --color --no-color
+{ logfile: 'test.log', color: false }
 ```
 
-`util.parseArgs` is experimental and behavior may change. Join the
+`util.parseArgs()` is experimental and behavior may change. Join the
 conversation in [pkgjs/parseargs][] to contribute to the design.
 
 -----

examples/limit-long-syntax.js

@@ -0,0 +1,30 @@
+'use strict';
+
+// How might I require long options with values use '='?
+// So allow `--foo=bar`, and not allow `--foo bar`.
+
+// 1. const { parseArgs } = require('node:util'); // from node
+// 2. const { parseArgs } = require('@pkgjs/parseargs'); // from package
+const { parseArgs } = require('..'); // in repo
+
+const options = {
+  file: { short: 'f', type: 'string' },
+  log: { type: 'string' },
+};
+
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+const badToken = tokens.find((token) => token.kind === 'option' &&
+  token.value != null &&
+  token.rawName.startsWith('--') &&
+  !token.inlineValue
+);
+if (badToken) {
+  throw new Error(`Option value for '${badToken.rawName}' must be inline, like '${badToken.rawName}=VALUE'`);
+}
+
+console.log(values);
+
+// Try the following:
+//    node limit-long-syntax.js -f FILE --log=LOG
+//    node limit-long-syntax.js --file FILE

examples/negate.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// How might I add my own support for --no-foo?
+
+// 1. const { parseArgs } = require('node:util'); // from node
+// 2. const { parseArgs } = require('@pkgjs/parseargs'); // from package
+const { parseArgs } = require('..'); // in repo
+
+const options = {
+  ['color']: { type: 'boolean' },
+  ['no-color']: { type: 'boolean' },
+  ['logfile']: { type: 'string' },
+  ['no-logfile']: { type: 'boolean' },
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+// Reprocess the option tokens and overwrite the returned values.
+tokens
+  .filter((token) => token.kind === 'option')
+  .forEach((token) => {
+    if (token.name.startsWith('no-')) {
+      // Store foo:false for --no-foo
+      const positiveName = token.name.slice(3);
+      values[positiveName] = false;
+      delete values[token.name];
+    } else {
+      // Resave value so last one wins if both --foo and --no-foo.
+      values[token.name] = token.value ?? true;
+    }
+  });
+
+const color = values.color;
+const logfile = values.logfile ?? 'default.log';
+
+console.log({ logfile, color });
+
+// Try the following:
+//   node negate.js
+//   node negate.js --logfile=test.log --color
+//   node negate.js --no-logfile --no-color
+//   node negate.js --no-logfile --logfile=test.log --color --no-color

examples/no-repeated-options.js

@@ -0,0 +1,29 @@
+'use strict';
+
+// How might I throw if an option is repeated?
+
+// 1. const { parseArgs } = require('node:util'); // from node
+// 2. const { parseArgs } = require('@pkgjs/parseargs'); // from package
+const { parseArgs } = require('..'); // in repo
+
+const options = {
+  ding: { type: 'boolean', short: 'd' },
+  beep: { type: 'boolean', short: 'b' }
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+const seenBefore = new Set();
+tokens.forEach((token) => {
+  if (token.kind !== 'option') return;
+  if (seenBefore.has(token.name)) {
+    throw new Error(`option '${token.name}' used multiple times`);
+  }
+  seenBefore.add(token.name);
+});
+
+console.log(values);
+
+// Try the following:
+//    node no-repeated-options --ding --beep
+//    node no-repeated-options --beep -b
+//    node no-repeated-options -ddd

examples/ordered-options.mjs

@@ -0,0 +1,35 @@
+// Now might I enforce that two flags are specified in a specific order?
+
+import { parseArgs } from '../index.js';
+
+function findTokenIndex(tokens, target) {
+  return tokens.findIndex((token) => token.kind === 'option' &&
+    token.name === target
+  );
+}
+
+const experimentalName = 'enable-experimental-options';
+const unstableName = 'some-unstable-option';
+
+const options = {
+  [experimentalName]: { type: 'boolean' },
+  [unstableName]: { type: 'boolean' },
+};
+
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+const experimentalIndex = findTokenIndex(tokens, experimentalName);
+const unstableIndex = findTokenIndex(tokens, unstableName);
+if (unstableIndex !== -1 &&
+  ((experimentalIndex === -1) || (unstableIndex < experimentalIndex))) {
+  throw new Error(`'--${experimentalName}' must be specified before '--${unstableName}'`);
+}
+
+console.log(values);
+
+/* eslint-disable max-len */
+// Try the following:
+//    node ordered-options.mjs
+//    node ordered-options.mjs --some-unstable-option
+//    node ordered-options.mjs --some-unstable-option --enable-experimental-options
+//    node ordered-options.mjs --enable-experimental-options --some-unstable-option

examples/tokens.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// This example is used in the documentation.
+
+// 1. const { parseArgs } = require('node:util'); // from node
+// 2. const { parseArgs } = require('@pkgjs/parseargs'); // from package
+const { parseArgs } = require('..'); // in repo
+
+console.log(parseArgs({ strict: false, tokens: true }));
+
+// Try the following:
+//    node tokens.js -xy --foo=BAR -- file.txt
+//    node tokens.js one -abc two