Remaining work for yargs v17 release

v17 is a large release, in which I’ve tried to address many long outstanding oddities related to middleware, async handlers, check functions, coerce functions, help output from commands.

There are still a few more tasks I would like to complete before we push it out the door:

• Node 10 is about to EOL, so I’d like to drop Node 10 before we take on the next major.
• skim through any recent docs issues and update docs pertinent to this release.
• land @OsmanAltun’s work on https://github.com/yargs/yargs/pull/1882
• ~figure out why WebPack has issues with our current export maps.~ The problem with bundlephobia is import.meta, which cannot be removed Refs: https://github.com/yargs/yargs/pull/1900
• ~try to reduce unpacked module size under 300kb (this is becoming increasingly difficult, since much of the size is due to lines of code).~ using terser to minify the common-js bundle works great, Refs: https://github.com/yargs/yargs/pull/1901
• make sure that https://github.com/DefinitelyTyped/DefinitelyTyped/pull/52169 is ready to merge, so that we don’t break TypeScript users for any length of time. (@seivan is pitching in on this work).
• update TypeScript docs. (@seivan is pitching in on this work).

---

If you would like to help QA, npm i yargs@next.

[seivan]

@bcoe I am just fixing things as I go along https://github.com/DefinitelyTyped/DefinitelyTyped/pull/52265

Honestly the types should be in here and generated by in the repo since this is a Typescript project after all, but more importantly should be true to the source code more than anything. Maintaining types externally seems like an accident waiting to happen.

More so, it’s painful to see so much potential for better types and API.

For instance a command should’t take more than a single middleware instead of an array and its return type would be combined with the types defined in builder before being passed to a handler That way a builder defines input’s that are expected and a middleware can then process those before moving to a handler

An example would be that a command that expects --path: string to some file and a middleware would use that to read the content of said file and return the updated arg.

The handler would then get {path: string, fileContent: string | undefined}.

[seivan]

@bcoe That sounds like a great idea, though I’d argue in order to keep things succinct, maybe omit certain approaches that aren’t taking advantage of the type system .

I did some tests of my own and cross-posting here:

export function createAdd(arg: Yargs.Argv): Yargs.Argv {
  return arg.command("add <name> [url]", "sample stuff", (addYarg) => {
    return addYarg
      .positional("name", { type: "string" }, demandOption: true)
      .positional("url", { type: "string" })
  }, (args) => {
     //args.name & args.url will be typed ✅
  })
}

While it does not work (out of the box) with CommandModule

const sourceAddCommand: Yargs.CommandModule = {
  command: ["add <name> [url]"],
  builder: (args) => {
    return args
      .positional("name", { type: "string", demandOption: true })
      .positional("url", { type: "string" })
  },

  handler: (args) => {
  //args & args.url ARE NOT typed ❌
  },
}

However there is partial support for just options and not positional. But you can’t have a builder and you lose descriptions, it literally skips over them when printing usage.

const sourceListCommand: Yargs.CommandModule<{}, {
  "available": {
    boolean: true,
    conflicts: "outdated",
   description: "Not visible ❌" 
   desc: "Not visible ❌",
  }, "outdated": {
    boolean: true,
    conflicts: "available",
   description: "Not visible ❌" 
   desc: "Not visible ❌" 
  }  
}> = {
  describe: "List Command",

  command: "list",
  handler: (args) => {
   // args.available & args.outdated are typed ✅
  },
}

To get typed arguments and avoid polluting the argument interface from other sub-commands in the same parent you need to wrap the entire sub-command in a function. To rephrase: sub-command siblings will get access to each other arguments and positional if they are not wrapped in a function.

   Yargs
    .default(YargsHelper.hideBin(process.argv))
    .scriptName(ProjectPackage.name)
    .command("mother <command>", "One of the main commands", (yargs) => {

      return [yargs]
        .map(makeFirstSubCommand)
        .map(createAdd)
      [0]
})
   . command("father <command>", "Other main command with its own subs", (yargs) => {

      return [yargs]
        .map(createAnotherSubCommandUnderFather)
        .map(someMoreUnderFather)
      [0]
})
.argv