Just a thought, I would be tempted to make tokens a class rather than a POJO with a kind property:

class Token {}
class OptionTerminator extends Token {}
class PositionalToken extends Token {}

With the classes exposed on the parseArgs export:

const {Token, PositionalToken} = parseArgs

Then I think you could just document the tokens as classes, similar to Buffer.blob, nested under the top level parseArgs docs, similar to how the docs are laid out for the JavaScript embedder API.

Even if these are made classes they should definitely expose a kind property - it's really awkward to work with tree nodes which lack such a property, which is why pretty much every parser in the world has them. (Similarly, the DOM has nodeName in addition to nodes being instances of distinct classes.)

Even if these are made classes they should definitely expose a kind property

Sounds good to me. I think it might be worth the class based approach, so that people could opt to check instanceof, if they're so inclined?

Should we consider making kind a Symbol, or is a string preferable?

Strings are traditional - they're a lot easier to work with, since you don't have to import them.

Just a thought, I would be tempted to make tokens a class rather than a POJO

It did cross my mind as soon as I added the kind property. 😄 .

The examples of Blob and AsyncResource and AsyncLocalStorage are all objects that authors will create themselves, with methods and state, where I think a Class adds more value.

I'm not against classes as such, but not seeing benefits in this case.

My 2 cents is we should go with the first one and make it less verbose, the "existing" version can be a bit confusing I think. But feel free to disagree, none option is perfect anyway, and we can always edit the docs later if we find a better layout.

I definitely find the existing one massively clearer; muddling things up with unnecessary TS/Java-ish terms and structure makes things more confusing.

Mixed opinions straight away! Thanks both for feedback.

I will leave it as is, barring further feedback.

I like that we could map the interface based approach directly to the TypeScript types we release on DefinitelyTyped.

But I don't feel super strongly, and would rather not block progress on the API (as @aduh95 says, we can edit the docs later).

Reapproving this PR 👍, @aduh95 are you happy as is?

The compact POJO description is a bit subtle to read. How about an expanded version with all the properties listed?

Proposed expanded

A returned token has two properties which are always defined,
and some other properties which vary depending on the kind:

• kind {string} One of 'option', 'positional', or 'option-terminator'.
• index {number} Index of element in args containing token. So the
  source argument for a token is args[token.index].

An option token has additional parse details
for an option detected in the input args:

• kind = 'option'
• index {number} Index of element in args containing token.
• name {string} Long name of option.
• rawName {string} How option used in args, like -f of --foo.
• value {string | undefined} Option value specified in args.
  Undefined for boolean options.
• inlineValue {boolean | undefined} Whether option value specified inline,
  like --foo=bar.

A positional token has just one additional property with the positional value:

• kind = 'positional'
• index {number} Index of element in args containing token.
• value {string} The value of the positional argument in args (i.e. args[index]).

An option-terminator token has only the base properties:

• kind = 'option-terminator'
• index {number} Index of element in args containing token.

Old compact

The returned tokens have properties describing:

• all tokens
  • kind {string} One of 'option', 'positional', or 'option-terminator'.
  • index {number} Index of element in args containing token. So the
    source argument for a token is args[token.index].
• option tokens
  • name {string} Long name of option.
  • rawName {string} How option used in args, like -f of --foo.
  • value {string | undefined} Option value specified in args.
    Undefined for boolean options.
  • inlineValue {boolean | undefined} Whether option value specified inline,
    like --foo=bar.
• positional tokens
  • value {string} The value of the positional argument in args (i.e. args[index]).
• option-terminator token

(Duplicate post of: pkgjs/parseargs#129 (comment))