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]

Didn't get much feedback on this. Closing in favour of #70 with new proposal.