refactor!: restructure configuration to take options bag (#63)

Per the discussion in #45 this PR restructures the current options API where each option is configured in three separate list and instead allows options to be configured in a single object.

The goal being to make the API more intuitive for configuring options (e.g. short, withValue, and multiples) while creating a path forward for introducing more configuration options in the future (e.g. default).

Co-authored-by: Benjamin E. Coe <[email protected]>
Co-authored-by: John Gee <[email protected]>
Co-authored-by: Jordan Harband <[email protected]>

Author: 4 people

README.md

@@ -28,7 +28,7 @@ It is exceedingly difficult to provide an API which would both be friendly to th
 - [🙌 Contributing](#-contributing)
 - [💡 `process.mainArgs` Proposal](#-processmainargs-proposal)
   - [Implementation:](#implementation)
-- [💡 `util.parseArgs(argv)` Proposal](#-utilparseargsargv-proposal)
+- [💡 `util.parseArgs([config])` Proposal](#-utilparseargsconfig-proposal)
 - [📃 Examples](#-examples)
   - [F.A.Qs](#faqs)
 
@@ -74,19 +74,16 @@ process.mainArgs = process.argv.slice(process._exec ? 1 : 2)
 
 ----
 
-## 💡 `util.parseArgs([argv][, options])` Proposal
+## 💡 `util.parseArgs([config])` Proposal
 
-* `argv` {string[]} (Optional) Array of argument strings; defaults
-  to [`process.mainArgs`](process_argv)
-* `options` {Object} (Optional) The `options` parameter is an
+* `config` {Object} (Optional) The `config` parameter is an
   object supporting the following properties:
-  * `withValue` {string[]} (Optional) An `Array` of argument
-    strings which expect a value to be defined in `argv` (see [Options][]
-    for details)
-  * `multiples` {string[]} (Optional) An `Array` of argument
-    strings which, when appearing multiple times in `argv`, will be concatenated 
-into an `Array`
-  * `short` {Object} (Optional) An `Object` of key, value pairs of strings which map a "short" alias to an argument; When appearing multiples times in `argv`; Respects `withValue` & `multiples`
+  * `args` {string[]} (Optional) Array of argument strings; defaults
+    to [`process.mainArgs`](process_argv)
+  * `options` {Object} (Optional) An object describing the known options to look for in `args`; `options` keys are the long names of the known options, and the values are objects with the following properties:
+    * `type` {'string'|'boolean'} (Optional) Type of known option; defaults to `'boolean'`; 
+    * `multiple` {boolean} (Optional) If true, when appearing one or more times in `args`, results are collected in an `Array`
+    * `short` {string} (Optional) A single character alias for an option; When appearing one or more times in `args`; Respects the `multiple` configuration
   * `strict` {Boolean} (Optional) A `Boolean` on wheather or not to throw an error when unknown args are encountered
 * Returns: {Object} An object having properties:
   * `flags` {Object}, having properties and `Boolean` values corresponding to parsed options passed
@@ -104,9 +101,9 @@ const { parseArgs } = require('@pkgjs/parseargs');
 ```js
 // unconfigured
 const { parseArgs } = require('@pkgjs/parseargs');
-const argv = ['-f', '--foo=a', '--bar', 'b'];
+const args = ['-f', '--foo=a', '--bar', 'b'];
 const options = {};
-const { flags, values, positionals } = parseArgs(argv, options);
+const { flags, values, positionals } = parseArgs({ args, options });
 // flags = { f: true, bar: true }
 // values = { foo: 'a' }
 // positionals = ['b']
@@ -115,25 +112,29 @@ const { flags, values, positionals } = parseArgs(argv, options);
 ```js
 const { parseArgs } = require('@pkgjs/parseargs');
 // withValue
-const argv = ['-f', '--foo=a', '--bar', 'b'];
+const args = ['-f', '--foo=a', '--bar', 'b'];
 const options = {
-  withValue: ['bar']
+  foo: {
+    type: 'string',
+  },
 };
-const { flags, values, positionals } = parseArgs(argv, options);
+const { flags, values, positionals } = parseArgs({ args, options });
 // flags = { f: true }
 // values = { foo: 'a', bar: 'b' }
 // positionals = []
 ```
 
 ```js
 const { parseArgs } = require('@pkgjs/parseargs');
-// withValue & multiples
-const argv = ['-f', '--foo=a', '--foo', 'b'];
+// withValue & multiple
+const args = ['-f', '--foo=a', '--foo', 'b'];
 const options = {
-  withValue: ['foo'],
-  multiples: ['foo']
+  foo: {
+    type: 'string',
+    multiple: true,
+  },
 };
-const { flags, values, positionals } = parseArgs(argv, options);
+const { flags, values, positionals } = parseArgs({ args, options });
 // flags = { f: true }
 // values = { foo: ['a', 'b'] }
 // positionals = []
@@ -142,11 +143,13 @@ const { flags, values, positionals } = parseArgs(argv, options);
 ```js
 const { parseArgs } = require('@pkgjs/parseargs');
 // shorts
-const argv = ['-f', 'b'];
+const args = ['-f', 'b'];
 const options = {
-  short: { f: 'foo' }
+  foo: {
+    short: 'f',
+  },
 };
-const { flags, values, positionals } = parseArgs(argv, options);
+const { flags, values, positionals } = parseArgs({ args, options });
 // flags = { foo: true }
 // values = {}
 // positionals = ['b']

index.js

@@ -2,11 +2,13 @@
 
 const {
   ArrayPrototypeConcat,
-  ArrayPrototypeIncludes,
+  ArrayPrototypeFind,
+  ArrayPrototypeForEach,
   ArrayPrototypeSlice,
   ArrayPrototypeSplice,
   ArrayPrototypePush,
   ObjectHasOwn,
+  ObjectEntries,
   StringPrototypeCharAt,
   StringPrototypeIncludes,
   StringPrototypeIndexOf,
@@ -16,7 +18,10 @@ const {
 
 const {
   validateArray,
-  validateObject
+  validateObject,
+  validateString,
+  validateUnion,
+  validateBoolean,
 } = require('./validators');
 
 function getMainArgs() {
@@ -53,41 +58,57 @@ function getMainArgs() {
   return ArrayPrototypeSlice(process.argv, 2);
 }
 
-function storeOptionValue(parseOptions, option, value, result) {
-  const multiple = parseOptions.multiples &&
-    ArrayPrototypeIncludes(parseOptions.multiples, option);
+function storeOptionValue(options, longOption, value, result) {
+  const optionConfig = options[longOption] || {};
 
   // Flags
-  result.flags[option] = true;
+  result.flags[longOption] = true;
 
   // Values
-  if (multiple) {
+  if (optionConfig.multiple) {
     // Always store value in array, including for flags.
-    // result.values[option] starts out not present,
+    // result.values[longOption] starts out not present,
     // first value is added as new array [newValue],
     // subsequent values are pushed to existing array.
     const usedAsFlag = value === undefined;
     const newValue = usedAsFlag ? true : value;
-    if (result.values[option] !== undefined)
-      ArrayPrototypePush(result.values[option], newValue);
+    if (result.values[longOption] !== undefined)
+      ArrayPrototypePush(result.values[longOption], newValue);
     else
-      result.values[option] = [newValue];
+      result.values[longOption] = [newValue];
   } else {
-    result.values[option] = value;
+    result.values[longOption] = value;
   }
 }
 
-const parseArgs = (
-  argv = getMainArgs(),
+const parseArgs = ({
+  args = getMainArgs(),
   options = {}
-) => {
-  validateArray(argv, 'argv');
+} = {}) => {
+  validateArray(args, 'args');
   validateObject(options, 'options');
-  for (const key of ['withValue', 'multiples']) {
-    if (ObjectHasOwn(options, key)) {
-      validateArray(options[key], `options.${key}`);
+  ArrayPrototypeForEach(
+    ObjectEntries(options),
+    ([longOption, optionConfig]) => {
+      validateObject(optionConfig, `options.${longOption}`);
+
+      if (ObjectHasOwn(optionConfig, 'type')) {
+        validateUnion(optionConfig.type, `options.${longOption}.type`, ['string', 'boolean']);
+      }
+
+      if (ObjectHasOwn(optionConfig, 'short')) {
+        const shortOption = optionConfig.short;
+        validateString(shortOption, `options.${longOption}.short`);
+        if (shortOption.length !== 1) {
+          throw new Error(`options.${longOption}.short must be a single character, got '${shortOption}'`);
+        }
+      }
+
+      if (ObjectHasOwn(optionConfig, 'multiple')) {
+        validateBoolean(optionConfig.multiple, `options.${longOption}.multiple`);
+      }
     }
-  }
+  );
 
   const result = {
     flags: {},
@@ -96,8 +117,8 @@ const parseArgs = (
   };
 
   let pos = 0;
-  while (pos < argv.length) {
-    let arg = argv[pos];
+  while (pos < args.length) {
+    let arg = args[pos];
 
     if (StringPrototypeStartsWith(arg, '-')) {
       if (arg === '-') {
@@ -110,30 +131,36 @@ const parseArgs = (
         // and is returned verbatim
         result.positionals = ArrayPrototypeConcat(
           result.positionals,
-          ArrayPrototypeSlice(argv, ++pos)
+          ArrayPrototypeSlice(args, ++pos)
         );
         return result;
       } else if (StringPrototypeCharAt(arg, 1) !== '-') {
         // Look for shortcodes: -fXzy and expand them to -f -X -z -y:
         if (arg.length > 2) {
           for (let i = 2; i < arg.length; i++) {
-            const short = StringPrototypeCharAt(arg, i);
+            const shortOption = StringPrototypeCharAt(arg, i);
             // Add 'i' to 'pos' such that short options are parsed in order
             // of definition:
-            ArrayPrototypeSplice(argv, pos + (i - 1), 0, `-${short}`);
+            ArrayPrototypeSplice(args, pos + (i - 1), 0, `-${shortOption}`);
           }
         }
 
         arg = StringPrototypeCharAt(arg, 1); // short
-        if (options.short && options.short[arg])
-          arg = options.short[arg]; // now long!
+
+        const [longOption] = ArrayPrototypeFind(
+          ObjectEntries(options),
+          ([, optionConfig]) => optionConfig.short === arg
+        ) || [];
+
+        arg = longOption ?? arg;
+
         // ToDo: later code tests for `=` in arg and wrong for shorts
       } else {
         arg = StringPrototypeSlice(arg, 2); // remove leading --
       }
 
       if (StringPrototypeIncludes(arg, '=')) {
-        // Store option=value same way independent of `withValue` as:
+        // Store option=value same way independent of `type: "string"` as:
         // - looks like a value, store as a value
         // - match the intention of the user
         // - preserve information for author to process further
@@ -143,18 +170,18 @@ const parseArgs = (
           StringPrototypeSlice(arg, 0, index),
           StringPrototypeSlice(arg, index + 1),
           result);
-      } else if (pos + 1 < argv.length &&
-        !StringPrototypeStartsWith(argv[pos + 1], '-')
+      } else if (pos + 1 < args.length &&
+        !StringPrototypeStartsWith(args[pos + 1], '-')
       ) {
-        // withValue option should also support setting values when '=
+        // `type: "string"` option should also support setting values when '='
         // isn't used ie. both --foo=b and --foo b should work
 
-        // If withValue option is specified, take next position argument as
-        // value and then increment pos so that we don't re-evaluate that
+        // If `type: "string"` option is specified, take next position argument
+        // as value and then increment pos so that we don't re-evaluate that
         // arg, else set value as undefined ie. --foo b --bar c, after setting
         // b as the value for foo, evaluate --bar next and skip 'b'
-        const val = options.withValue &&
-          ArrayPrototypeIncludes(options.withValue, arg) ? argv[++pos] :
+        const val = options[arg] && options[arg].type === 'string' ?
+          args[++pos] :
           undefined;
         storeOptionValue(options, arg, val, result);
       } else {
@@ -163,7 +190,6 @@ const parseArgs = (
         // save value as undefined
         storeOptionValue(options, arg, undefined, result);
       }
-
     } else {
       // Arguments without a dash prefix are considered "positional"
       ArrayPrototypePush(result.positionals, arg);