Decide result conventions (includes detailed examples of client use)

[shadowspawn]

This repo started out with a plan, which was not immediately clear to new-comers (me!). In trying to clarify the naming, I initiated a change in the results conventions which has not been completed (#12 #22 #23). So let's regroup and get the naming and README and code all in sync again.

Which convention will we use?

• (1) "existence" property in result, which records true for any option used anyhow (and a values property)
• (2) flags/values with separate results for flags and values
• (3) (combined results is included for comparison with other libraries, not as a contender)

I propose in absence of anyone with strong preference for flags/values that we go back to "existence" conventions. (I think flags/values is perfectly workable, but it was somewhat accidental!)

---

I wanted to explore what client code would look like for various conventions used in the result of the parse. Here are my client scenarios:

Primary use cases for simple use (no error check because optimistic or strict)

• detect boolean flag used
• detect withValue option used and get value

Other use cases for bring-your-own validation checks:

• detect boolean flag misused
• detect withValue option misused
• detect option used in any form (valid or invalid, whether specified in withValue or not)

These examples include some behaviours which are under discussion or touched on elsewhere (especially the misuse cases #24 and #25). Most are being discussed separately, so please join those discussions rather than comment on special cases here unless it is relevant to your choice of preferred high level convention.

[shadowspawn]

(1) Existence

Based on original approach for this repo:

• options: track the existence of an option in parsed args no matter whether used as a flag or with a value
• values: option values (plain boolean flags do not have a value)

(I think this is representative of what you intended @darcyclarke. Anyone feel free to correct me if I got it wrong in a way that detracts from the functionality!)

// Primary use cases for simple use (no error check because optimistic or strict).
// detect boolean flag used
const { options, values } = parseArgs(['--foo']);
// { options: { foo: true }, values: {} }
const fooUsed = options.foo;

// detect withValue option used and get value
const { options, values } = parseArgs(['--foo=bar'], { withValue: ['--foo'] });
// { options: { foo: true }, values: { foo: 'bar' } }
const fooUsed = options.foo;
const fooValue = values.foo;

// Other use cases for bring-your-own validation checks.
// detect boolean flag misused
const { options, values } = parseArgs(['--foo=bar']);
// { options: { foo: true }, values: { foo: 'bar' } }
const fooUsageError = /* options.foo && */ values.foo !== undefined;

// detect withValue option misused
const { options, values } = parseArgs(['--foo'], { withValue: ['--foo'] });
// { options: { foo: true }, values: {} }
const fooUsageError = options.foo && values.foo === undefined;

// detect option used in any form (valid or invalid, whether specified in withValue or not)
const { options, values } = parseArgs(mysteryArgs, mysteryOptions);
const fooUsed = options.foo;

Reference comments:

• Behaviour for zero config --foo=a ? #24 (comment)
• Behaviour for zero config --foo=a ? #24 (comment)
• Behaviour for withValue --foo followed by --bar ? #25 (comment)

[shadowspawn]

(2) flags/values

This is the exclusive flags/values approach.

// Primary use cases for simple use (no error check because optimistic or strict).
// detect boolean flag used
const { flags, values } = parseArgs(['--foo']);
// { flags: { foo: true}, values: {} }
const fooUsed = flags.foo;

// detect withValue option used and get value
const { flags, values } = parseArgs(['--foo=bar'], { withValue: ['--foo']});
// { flags: {}, values: { foo: 'bar' } }
const fooUsed = values.foo !== undefined;
const fooValue = values.foo;

// Other use cases for bring-your-own validation checks.
// detect boolean flag misused
const { flags, values } = parseArgs(['--foo=bar']);
// { flags: {}, values: { foo: 'bar' } }
const fooUsageError = values.foo !== undefined;

// detect withValue option misused
const { flags, values } = parseArgs(['--foo'], {withValue: ['--foo']});
// { flags: { foo: true }, values: {} }
const fooUsageError = flags.foo;

// detect option used in any form (valid or invalid, whether specified in withValue or not)
const { flags, values } = parseArgs(mysteryArgs, mysteryOptions);
const fooUsed = flags.foo || values.foo !== undefined;

[shadowspawn]

(3) Combined values

combinedValues storing true for boolean flag, string for value.

// Primary use cases for simple use (no error check because optimistic or strict).
// detect boolean flag used
const { combinedValues } = parseArgs(['--foo']);
// { combinedValues: { foo: true } }
const fooUsed = combinedValues.foo;

// detect withValue option used and get value
const { combinedValues } = parseArgs(['--foo=bar'], {withValue: ['--foo']});
// { combinedValues: { foo: 'bar' } }
const fooUsed = combinedValues.foo != undefined;
const fooValue = combinedValues.foo;

// Other use cases for bring-your-own validation checks.
// detect boolean flag misused
const { combinedValues } = parseArgs(['--foo=bar']);
// { combinedValues: { foo: 'bar' } }
const fooUsageError = typeof combinedValues.foo === 'string';

// detect withValue option misused
const { combinedValues } = parseArgs(['--foo'], {withValue: ['--foo']});
// { combinedValues: { foo: true } }
const fooUsageError = combinedValues.foo === true;

// detect option used in any form (valid or invalid, whether specified in withValue or not)
const { combinedValues } = parseArgs(mysteryArgs, mysteryOptions);
const fooUsed = combinedValues.foo !== undefined;

[shadowspawn]

After struggling with the error cases and having a fresh insight, redid the examples. Looks like a flag, stored like a flag. Looks like a value, stored like a value.

#25 (comment)
#24 (comment)

[bcoe]

@shadowspawn based on your exploration, what changes are you recommending? (is one recommendation the addition of combinedValues?).

edit: from reading them through, your examples of additional parse goals seem great to me 😄 I think the tldr; is that the parser output is a little weird as it stands right now, e.g.,

> parseArgs(['--bar', '99', '--foo'], {withValue: ['bar']})
{
  flags: { bar: true, foo: true },
  values: { bar: [ '99' ], foo: [ undefined ] },
  positionals: []
}

☝️ why is foo undefined (which you summarize in #25).

---

Unless anyone objects, I say we flesh out the test suite with your examples in this issue -- _perhaps separately opening a discussion about combinedValues?

[shadowspawn]

Short version: I recommend we actually implement one of these approaches! 😄 I don't mind which one too much.

Long version

This issue is to layout three approaches to the parsing results to aid in deciding which single approach we are implementing, and proceed with confidence.

The current state of this repo is the naming and README describe the xor flag/value approach (due to #12 #23), the second approach listed above. The current code does not implement this approach.

The current code still implements the options/values approach! First approach listed above. My PR to finish the conversion to flags/values eventually got marked as do-not-merge (#26), perhaps because Darcy made a lot of comments, or perhaps because primordials was underway.

(To be clear and less dramatic, the difference between options/values and xor flags/values is minor after nailing some of the details. The difference is basically whether true is stored in flags/options for a withValue option. The options approach stores true for all options, flags stores true only for flags. As per example code above.)

I decided to give the original vision a decent look with the new information making my understanding of the intent clearer. One of the speculated advantages for options/values was it avoiding losing some information (#13, #24 (comment)) and I wanted to explore that. Having worked through the cases, I don't see a difference in the information available and the questions that can be answered with any of the three approaches.

There are issues I want to fix in the original code too which were also in (#26). Per your example of the current output: #38 (comment)

• why is foo undefined?
• what are foo and bar returning arrays? (Unnecessary arrays in result values? #19)

[shadowspawn]

I think the tldr; is that the parser output is a little weird as it stands right now

That is a great summary of what I have been trying to improve since I found this project. 😄

[bcoe]

@darcyclarke @shadowspawn I think, perhaps, center conversation on #34. Once a README is landed with examples of agreed upon parse goals, we can move the implementation to match?

[shadowspawn]

I think here is a good place to decide what convention we are intend to use in the results, with both example results and example author usage. #34 and open issues are all focused on something different. I'll update this issue from "exploring" to "deciding" tonight.

For background, the issue and discussion that led to flags/values was #12. I am ok with going back to the existence convention if desired.

(The two issues that affect the examples here are #24 and #25 where the user arguments do not match the author configuration. Working through these examples made me rethink what made things easier for author and more consistent, and it still feels solid after sleeping on it to store results consistent with the user intent.)

[shadowspawn]

Reworked issue into making a choice, rather than just exploring.