util: parseArgs should support `required` in options[key]

[himself65]

What is the problem this feature will solve?

I'm building a CLI that creates some instances by id and name. But I have to check if all options are filled by the user one by one.

const args = process.argv.slice(2)

const result = parseArgs({
  args,
  options: {
    owner: {
      type: 'string'
    },
    repo: {
      type: 'string'
    }
  }
})

// imaging you will have tens of options in your CLI
if (result.values.repo == null || result.values.owner == null) {
  throw new Error('require parameters')
}

./build.js --owner=himself65 --repo=xxx

What is the feature you are proposing to solve the problem?

Add required option.

parseArgs({
  args,
  options: {
    owner: {
      type: 'string',
      required: true
    },
    repo: {
      type: 'string',
      required: true
    },
    force: {
      type: 'boolean',
      // by default, required is false
    },
  }
})

What alternatives have you considered?

No response

[tniessen]

Aren't required positional arguments far more common than required options? I think Node.js should follow POSIX conventions when it comes to parsing arguments, and those seem to heavily favor positional arguments for required values (see GNU core utilities, for example).

[shadowspawn]

Positional arguments are suitable for 1 or 2 arguments, but UX guides often recommend using options when there are more to make their meaning clearer. In your example with only two options, at least one of them would make sense as a positional argument and perhaps the other one could be deduced.

// imaging you will have tens of options in your CLI

Normally most or all options are optional. So it isn't very likely people will have lots of required options.

An earlier version of the Python library discouraged required options on principle (optParse). The current version has this to say: https://docs.python.org/3/library/argparse.html#required

Note Required options are generally considered bad form because users expect options to be optional, and thus they should be avoided when possible.

[tniessen]

I agree with @shadowspawn. I would say that required options are relatively uncommon.

A required: boolean option gives little flexibility. For example, how would I implement a --help option when I have other options that are required unless --help is used?

On the contrary, usually, each option value has to be validated in some way anyway. Its existence or non-existence is usually not the only validation criterion.

[jhmaster2000]

This would probably be a separate issue, but what about incompatible and requires fields? While unconditionally required options are rare and frowned upon, dependent and incompatible options are far more common. Both these fields would be of type string[], containing names of other options in the current parseArgs object:

parseArgs({
  args,
  options: {
    owner: {
      type: 'string',
      requires: ['repo'],
      incompatible: ['org'],
    },
    org: {
      type: 'string',
      requires: ['repo'],
      // no need to specify incompatible: ['owner']
      // it should work both ways on either one
      // but it can also be explicitly on both if desired
    },
    repo: {
      type: 'string',
      // details on requiresOne further down
      requiresOne: ['owner', 'org'],
    },
    url: {
      type: 'string',
      incompatible: ['repo', 'org', 'owner'],
    }
  }
});

The above code would result in:

# Allowed
foo --url=https://gh.com/user/proj
foo --owner=user --repo=proj
foo --org=nodejs --repo=node
foo

# Not allowed
foo --url=https://... --owner=user
foo --org=nodejs --url=https://...
foo --repo=proj --owner=user --url=https://...
foo --owner=user --org=nodejs --repo=proj
foo --repo=node
foo --owner=user
foo --org=nodejs

• All of these new fields would default to an empty array []. If any of them specify either their own option or a non-existent option it should throw a TypeError.
• requires is directional, if --a requires --b but --b doesn't require --a, foo --b is valid but foo --a is not.
• requiresOne is a variation of requires where the array is treated as a list of ORs instead of ANDs.
• requires and requiresOne can be used together without issue, but naturally overlapping options between the two will have higher precedence on requires.
• incompatible is bidirectional, if --a declared itself incompatible with --b, then --b is also implicitly incompatible with --a. Explicitly marking both incompatible with each other is fine and does nothing extra.
• If a conflict between the fields requires* and incompatible of two options or one by itself happens, it should throw a TypeError.

[shadowspawn]

This would probably be a separate issue, but what about incompatible and requires fields?

Nice detailed description. I suggest opening as a separate issue if you want more visibility.

I think of these as beyond-basic parsing options. I don't think parseArgs itself needs them and the "vision" for parseArgs was for a basic robust option parser, but that isn't currently a rule and I expect features will be considered case by case.

[jhmaster2000]

I think of these as beyond-basic parsing options. I don't think parseArgs itself needs them and the "vision" for parseArgs was for a basic robust option parser, but that isn't currently a rule and I expect features will be considered case by case.

I was not aware of the original "vision" for it and its a fair point, but as a counterpoint on the other hand, in this particular case I would argue it makes sense given it only adds optional slightly more advanced (but still arguably pretty basic) configuration, so in my opinion it'd be fine to add whilst still keeping that original vision.

I will make a separate issue for this soon for further discussion and update this comment linking to it when I do.
Separate issue opened at #45062

[tniessen]

I don't think parseArgs itself needs them and the "vision" for parseArgs was for a basic robust option parser

IMHO, the same can be said about default values, which are trivial to do in userland (see, for example, #44631 (comment)) but which were stilled added.

My main concern here is adding complexity both to the API surface and to the implementation while still not providing a complete solution. The goal has not been to provide a full-fledged and feature-complete argument parser. In this particular case, even with the three newly proposed options (requires, requiresOne, incompatible) not all sets of subsets can be described, so it is not a complete solution to describing relations between the existence of options, while significantly increasing complexity.

[shadowspawn]

IMHO, the same can be said about default values, which are trivial to do in userland (see, for example, #44631 (comment)) but which were stilled added.

Yes. Yes, indeed. Default values could have been left out! However, there were multiple people looking for defaults who still wanted it despite the relative ease of implementation or alternatives. (I speculate a partial factor may be people not familiar or comfortable with destructuring with defaults.)

Checking for champion for not adding: pkgjs/parseargs#142 (comment)