Decide result conventions (includes detailed examples of client use)

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.

@darcyclarke

(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:

(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;

(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;

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

Navigation Menu

Repository navigation

Decide result conventions (includes detailed examples of client use) #38

(1) Existence

(2) flags/values

(3) Combined values

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Decide result conventions (includes detailed examples of client use) #38

Description

Activity

shadowspawn commented on Jan 20, 2022

(1) Existence

shadowspawn commented on Jan 20, 2022

(2) flags/values

shadowspawn commented on Jan 20, 2022

(3) Combined values

shadowspawn commented on Jan 21, 2022

bcoe commented on Jan 22, 2022

shadowspawn commented on Jan 22, 2022

shadowspawn commented on Jan 22, 2022

bcoe commented on Jan 23, 2022

shadowspawn commented on Jan 23, 2022

shadowspawn commented on Jan 24, 2022

shadowspawn commented on Feb 27, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions