Improve API for configuring a high number of arguments

[aaronccasanova]

I wanted to play devils advocate on the design of the parseArgs options object. Are there any concerns that the options object will become unwieldy as the number of arguments grow? While I am still catching up on prior discussions and understanding the target audience of this tool, I imagine creating large scale CLIs (e.g. aws-cli, git, docker, etc.) will be challenging to configure as configuring a single argument requires setting multiple top level keys (e.g. withValues, multiples, short).

I wanted to gauge folks opinion on allowing users to set all the configurations for a single argument in one object.

(Current) Example configuring large scale CLI options

parseArgs(argv, {
  withValue: [
    'foo',
    // +500 more values
  ],
  multiples: [
    'foo',
    // +500 more multiples
  ],
  short: {
    f: 'foo',
    // +500 more shorts
  },
})

(Proposed) Example configuring large scale CLI options

Keeping the same terminology established thus far.

parseArgs(argv, {
  args: {
    foo: {
      short: 'f',
      withValue: true,
      multiples: true,
    },
    // +500 more args
  },
})

[ljharb]

That seems like a useful semver-minor addition in the future, when usage patterns are well-understood.

[shadowspawn]

Fair question. I think the initial focus is on keeping it simple, and large scale CLI is not a concern for now. (And a large scale program could repackage the one-object configuration fairly easily.)

[aaronccasanova]

I think the initial focus is on keeping it simple

Totally understand the desire to keep things simple. However, I don't believe the proposed suggestion adds complexity to the implementation or configuration. For example, I modified a few lines in the current implementation and enabled individual configuration objects: main...aaronccasanova:feat/improve-options-api

const argv = ['--f', 'foo1', '--foo', 'foo2', '--bar', 'baz'];

const parsed = parseArgs(argv, {
  args: {
    foo: {
      short: 'f',
      withValue: true,
      multiples: true,
    },
  },
});

console.log('parsed:', parsed);

large scale CLI is not a concern for now

Being that this is intended for Node core, I would have thought otherwise.

Appreciate the quick response and feedback!

[ljharb]

My concern about including it now isn't about the code complexity, it's about the API surface, and the design space.

[shadowspawn]

For background, the Intended Audience from the "Initial Proposal". (May or may not reflect what eventuates!)

nodejs/node#35015 (comment)

Intended Audience

It is already possible to build great arg parsing modules on top of what Node.js provides; the prickly API is abstracted away by these modules. Thus, process.parseArgs() is not necessarily intended for library authors; it is intended for developers of simple CLI tools, ad-hoc scripts, deployed Node.js applications, and learning materials.

It is exceedingly difficult to provide an API which would both be friendly to these Node.js users while being extensible enough for libraries to build upon. We chose to prioritize these use cases because these are currently not well-served by Node.js' API.

[aaronccasanova]

That's a helpful bit of context! Thanks for the reference @shadowspawn

[bcoe]

@aaronccasanova, I'm with @ljharb on erring on the side of a smaller API for MVP. With the goal initially being to support simple throw away CLIs and code samples.

I'm hopeful we might be able to target Node 18, or Node 19 with the MVP, so the tighter we can keep the API the better, hence trying to keep behavior constrained.

I think this work could immediate be a great follow up, and a good place to contribute to the Node.s codebase.

[bakkot]

@bcoe What about making this the only way to configure options? It seems more natural, to me: it means you're describing each argument in one place, rather than splitting up the configuration for each option across several fields. And if it's the only way to do it, it doesn't increase the API surface.

const parsed = parseArgs(argv, {
  args: {
    foo: {
      withValue: true,
    },
  },
});

does not seem noticeably harder to use than

const parsed = parseArgs(argv, {
  withValue: ['foo'],
});

and has the advantage of being a lot more natural as soon as you get at all beyond that:

const parsed = parseArgs(argv, {
  args: {
    foo: {
      withValue: true,
      multiple: true,
    },
    bar: {
      withValue: true,
    },
  },
});

is much easier to understand than

const parsed = parseArgs(argv, {
  withValue: ['foo', 'bar'],
  multiple: ['foo'],
});

since the latter requires you to scan multiple lists to figure out how foo is going to behave. More importantly, it also matches how people are likely to be accustomed to doing configuration: the properties for each field are set within that field, rather than having lists of fields-with-this-property.

[shadowspawn]

does not seem noticeably harder to use than

I think using nested objects is noticeably harder. The simplest configuration is a triply nested object. I think that is more challenging for a beginner to scan, or indeed type.

Smaller comments:

• Multiples are going to be relatively rare. But there will still often be two properties in place as I think short options are pretty routine. So your comments about how to slice still apply.
• I personally slightly prefer the objects from a purist point of view, but I still prefer the arrays from a pragmatic point of view for the initial target audience.

[bakkot]

I don't think "nested objects" as a concept is terribly confusing for most beginners. In my experience that's not the kind of complexity which usually trips people up when starting out. "These two things are implicitly related despite having no syntactic connection", on the other hand, definitely is.

So I think the above approach is better even from a strictly pragmatic point of view when optimizing for the experience of beginners.

That said, you can quite reasonably drop a level of indentation by having the second argument just be args, and having remaining options be in an optional third parameter. Then you have only doubly-nested objects, which is the same level of nesting as in the current API.

That is:

const parsed = parseArgs(argv, {
  foo: {
    withValue: true,
    multiple: true,
  },
  bar: {
    withValue: true,
  },
}, /* any other options */);

[bcoe]

What about making this the only way to configure options?

@shadowspawn @darcyclarke @ljharb, if we went with the nested object approach for configuration, I feel like strict becomes more natural, since all your valid arguments are defined in one place ... For flags, we could allow any empty object for configuration, or flag: true?

[ljharb]

I’m ambivalent on either of the two ways to configure, but i feel strongly that non-strict is a very bad default, so if this argument form comes with default-strict, I’m super on board.

[aaronccasanova]

I think using nested objects is noticeably harder.

I used a nested object structure for three reasons:

1. Allows for more top level configurations
2. Minimizes the chances of introducing breaking changes in future iterations
3. Easier to static type check

1. Allows for more top level configurations

e.g.

parseArgs(argv, {
  strict: true,
  ...moreTopLevelConfigs,
  args: {...}
})

3. Easier to static type check

e.g.

type ParseArgsOptions = {
  strict?: boolean
  args?: {
    [arg: string]: { // 👈 Isolated from top level configs
       short?: string
       withValue?: boolean
       multiples?: boolean
    }
  }
}

That said, you can quite reasonably drop a level of indentation by having the second argument just be args

We may not necessarily care about this here, but dropping a level of indentation will result in flaky types if we want to allow more top level configurations:

e.g. How do you accurately type this example:
TSPlayground - with nested object structure
TSPlayground - without nested object structure

parseArgs(argv, {
  strict: true,
  foo: {
    short: 'f',
    withValue: true,
  },
  bar: false, // Should error, not a valid arg value or top level config
})

// This would pass, but is no longer valid or representative of the implementation:
type ParseArgsOptions = {
  strict?: boolean
  [arg: string]: boolean | {
     short?: string
     withValue?: boolean
     multiples?: boolean
  }
}