Behaviour for zero config --foo=a ?

[shadowspawn]

I suggest the intent of the user is clear, and the value should be stored?

Added TL;DR proposal: #24 (comment)

---

The initial README did not clarify what happens with --foo=a with no configuration, as the result was overwritten by repeated option --foo b.

I assumed the value would be stored in update to README in #23, which has landed.

The current implementation ignores the value unless withValue is set for foo.

[bcoe]

@shadowspawn are you thinking that --foo-a should implicitly behave as if foo was configured withValue? This seems like a good assumption to me.

[darcyclarke]

I don't think this is a good idea. We should be keeping as few assumptions out of this implementation as possible & force the user to define when/if values are to be captured & returned or not (which puts them into a better overall experience).

What I think is happening here, & is concerning, is that we've changed the meaning of args (aka. flags) which is causing us to loose information & muddy context along the way.

Looking back (ref. https://github.com/pkgjs/parseargs/blob/3f057c1b158a1bdbe878c64b57460c58e56e465f/README.md), args (aka. flags) was meant to track the existence of an argument no matter what its value, or the provided function options, were. withValue was meant to define whether to return any value back in values (ie. a parsed string from "key=value", a captured positional string or undefined).

Looking at the most recent version of the spec (2022/01/16):

// unconfigured
const argv = ['-f', '--foo=a', '--bar', 'b'];
const options = {};
const { flags, values, positionals } = parseArgs(argv, options);
// flags = { f: true, bar: true }
// values = { foo: 'a' }
// positionals = ['b']

I now need to do two different lookups to find the existence of an argument, & we've created an arbitrary delineation of two "types" of arguments (ie. ones with & without values). Worse yet, afaict, there's no way to determine existence, vs. value, when using withValue.

// unconfigured
const argv = ['-f', '--foo=a', '--bar', 'b'];
const options = {};
const { flags, values, positionals } = parseArgs(argv, options);
const fooExists = (flags.foo || Object.keys(values).foo)

// `withValue`
const argv = ['-f', '--foo=a', '--bar', 'b'];
const options = { 
  withValue: [ 'foo' ] 
};
const { flags, values, positionals } = parseArgs(argv, options);
const fooExists = (flags.foo || Object.keys(values).foo) // always true

Previously, I could write the following no matter what the options...

const { args, values, positionals } = parseArgs(argv, options);
const fooExists = !!args.foo

Either way, my knee-jerk reaction here is that if we assume parsing of --key=value then...

• we need to determine what the value is we return for --key= with & without withValue: [ 'key' ] defined (potentially making further assumptions)
• we need to re-evaluate withValue as a whole (as it seems like it would only be relevant for positional value association/parsing now)

[shadowspawn]

What I think is happening here, & is concerning, is that we've changed the meaning of args (aka. flags) which is causing us to loose information & muddy context along the way.

I was a driver for that, sorry. The intended usage and potential benefits were not apparent to me (#13).

I am not sure there is more information with the original implementation, but I'll work through your example carefully before commenting further. Thanks for the detail, and I look forward to discussing the issues raised!

1. What behaviour were you expecting for an unconfigured --key=value?

2. Is your primary use case a user whipping up a CLI, or using this as a base for a more robust and fuller implementation?

[darcyclarke]

1. What behaviour were you expecting for an unconfigured --key=value?

My original thought was thatkey would get added to flags & value would be ignored (I'm not opposed to changing this though, see more below)

const { flags, values, positionals } = parseArgs(['--foo=a']);
// flags = { foo: true }
// values = { }
// positionals = []

2. Is your primary use case a user whipping up a CLI, or using this as a base for a more robust and fuller implementation?

Both. The ease of use & understanding parseArgs().flags.foo returning the existence of --foo captures both audiences.

Take these two examples:

// node program.js --foo=
parseArgs().flags.foo // undefined
parseArgs().values.foo // undefined

// node program.js --foo
parseArgs().flags.foo // true
parseArgs().values.foo // undefined

This feels like non-deterministic behavior as in both cases I've set a flag but only changed how I've declared it's value. If I were able to rely on flags always returning true when a flag existed I can write better programs or abstractions.

Example: quick & dirty...

// node program.js --debug # or...
// node program.js --debug="Some debugger prefix"
if (parseArgs().flags.debug) {
  const prefix = parseArgs().values.debug || 'Debugger'
  console.log(`${prefix}:`, process)
}

Example: more fully-baked validation & aliasing...

const { flags, values } = parseArgs({ withValue: ['org', 'force'] })
const settings = {
  org: {
    alias: 'b',
    usage: 'run this program with `--org <name>`',
    required: true,
    validate: Object.toString
  },
  force: {
    alias: 'f',
    usage: 'run this program with `--force` to force some action',
    default: false,
    validate: (value) => {
      if (~['true','false'].indexOf(value.toLowerCase())) {
        return Boolean(value)
      }
      throw Error('Type validation error!')
    }
  }
}
Object.entries(settings).map(([flag, option]) => {
  const isDefined = flags[arg] || flags[option.alias]
  const value = values[flag] || values[option.alias]
  if (!isDefined && option.required)
    throw Error('Required arguments are missing', option.usage)
  if (defined && option.validate)
    values[flag] = option.validate(value)
})

---

On "zero config"...

I'm honestly not that opposed to parsing --key=value by default but it does change how I see withValue & it's usefullness.

Changes & explicit rules we might want to consider if we go this route...

• drop withValue
• introduce acceptsPositionalValues(or some better name, we can bikeshed here)
• --key= parses to undefined
• --key=value parses to a string value
• --key=value1 --key value2 parse things differently with & without acceptsPositionalValues &/or multiples options associated with the key

Examples of this in practice...

Notably, these all include/respect the idea that we'd return the existence of flags again in flags (as referenced above):

// no value
parseArgs(['--foo=']) 
/*
{
  flags: { foo: true }, 
  values { foo: undefined },
  positionals: []
}
*/

// key=value
parseArgs(['--foo=a']) 
/*
{
  flags: { foo: true }, 
  values { foo: 'a' },
  positionals: []
}
*/

// multiple flags, no options
parseArgs(['--foo=a', '--foo']) 
/*
{
  flags: { foo: true }, 
  values { foo: undefined },
  positionals: []
}
*/

// multiple flags, with `multiples` option
parseArgs(['--foo=a', '--foo'], { multiples: [ 'foo' ] }) 
/*
{
  flags: { foo: true }, 
  values { foo: [ 'a', undefined ] },
  positionals: []
}
*/

// positional, no options 
parseArgs(['--foo=', 'bar']) 
/*
{
  flags: { foo: true }, 
  values { foo: 'a' },
  positionals: ['bar']
}
*/

// positional, with `acceptsPositionalValues` option
parseArgs(['--foo=', 'bar'], { acceptsPositionalValues: ['foo'] }) 
/*
{
  flags: { foo: true }, 
  values { foo: 'bar' },
  positionals: []
}
*/

[shadowspawn]

Examples of this in practice...

A quick note that I think --foo= should set the value to the empty string, not to undefined.

(Early morning here. Hopefully I will have time tonight for some in depth replies.)

[darcyclarke]

"(Early morning here. Hopefully I will have time tonight for some in depth replies.)"

No worries. Take your time. I know I wrote a lot (apologies; I'm playing catch-up for not having time over the last ~3-6months)

"A quick note that I think --foo= should set the value to the empty string, not to undefined.

We might just have to agree to diasgree 🤷🏼‍♂️ (I noted as much in our other thread). I don't feel super strongly about it though unless that decision effects if/how we throw in strict mode (ie. would we consider --foo= an error if withValue: [ 'foo' ] & strict: true were both defined... even though we would parse that "" otherwise 🤔 something to consider imo).

For me, my expectation is that --foo & --foo= would be the same (ie. undefined). --foo="" is explicitly an empty string.

I know the context is somewhat different but in JS... v not relevant

let foo=;    // is an error
let foo;     // is undefined
let foo='';  // is an empty string

[shadowspawn]

For normal command-line use, there is parsing going on from shell script before node or client code every see the args. I think this makes the distinction between --foo= and --foo="" moot, they look the same by the time they reach parseArgs. Simple example:

$ echo --foo=""
--foo=
$ echo --foo=  
--foo=

[darcyclarke]

With that in mind, I'd think that --foo should probably be treated the same way... so --foo="", --foo= & --foo all set values.foo === ""; thoughts?

[ljharb]

--key= should parse to the empty string, just like in a URL query string. --key should parse to either undefined or true.

[shadowspawn]

I'll pick up this comment first because I think it highlights some key points of confusion or contention. I won't write an essay about every two sentences! And epic exposition in later comment #24 (comment) , thanks @darcyclarke , I'm going to read through that multiple times before commenting on it.

I now need to do two different lookups to find the existence of an argument, & we've created an arbitrary delineation of two "types" of arguments (ie. ones with & without values).

There are different user affordances provided by either approach. To be clear, I am not against your original intentions now you have explained it. From experience with Commander and reading about Yargs and Minimist, I expected a single result object rather than a pair and came up with a different pattern to try and justify the pair: an explicit delineation of two types of arguments, the ones with and without values. I actually thought this might have been part of the original intent, some sort of type safety, one holds booleans and one holds strings in the normal case. I was way wrong about that intent. :-)

Let's assume for a moment we stick with the current suggestion, misguided as it may be. I don't think there is loss of information or difficulty in use.

As the author, I know what I am expecting. If I want to check a boolean flag has been used, I simply check flags[key]. If I want to check an option for which I am expecting a value, if I am ignoring empty strings I can simply check !!values[key], or to include the empty string then values[key] !== undefined.

If I am testing for the existence of an argument with or without a value, I do need to check two values. But this does not seem like a happy-path case.

Worse yet, afaict, there's no way to determine existence, vs. value, when using withValue.

I don't think I understand. If foo is included in withValue, it will have a value in values if it was specified on the command-line. It will not have a value in values if it was not specified on the command-line. The tricky case is --foo without a positional to supply the value (#25) and the suggestion was to store undefined. (I think storing undefined should be be avoided in happy-path cases because it is a pain to test for and a pain to talk about, the property is defined with the value undefined. More reasonable in unhappy path cases like this one.)