Devex: Wrapper for node:utils parseArgs

[jimlerza]

Argument Parser for Shell Scripts Written in TypeScript

We have several scripts now that use node:utils parseArgs to parse command-line arguments, and it works great! Unfortunately, however, the scripts that use it have to implement a ton of code, to the extent that in some cases the code to configure and utilize parseArgs ends up being longer than the rest of the script combined.

Here I've written a wrapper that we can call that does all of that work for us, and centralizes some of the text transformation stuff we were slapping on afterwards.

How to Use the Argument Parser in a Shell Script

Let's say you want the $1 (first positional) argument to be required and you want to optionally support two additional arguments. Now you can just put this at the top of your script:

const scriptConfig: ScriptConfig = {
  description: 'some-script.ts - works wonders',
  parameters: {
    eventCode: {
      position: 0,
      required: true,
      type: 'string',
    },
    fiscal: {
      default: false,
      short: 'f',
      type: 'boolean',
    },
    year: {
      default: '2024',
      short: 'y',
      transform: 'number',
      type: 'string',
    },
  },
};

And then elsewhere in the script you can get the values thusly:

const { eventCode, fiscal, year } = parseArguments(scriptConfig);

In Action

Given the configuration above, say you call your script like so:

npx ts-node --transpile-only scripts/some-script.ts NOA -f

The argument parser will return the following:

{
  eventCode: 'NOA',
  fiscal: true,
  year: 2024,
};

Self-Documenting

All scripts that utilize the argument parser will get a --help flag that, when provided, will output usage information automatically generated from the ScriptConfig configuration object.

Again, given the configuration above, say you call your script like so:

npx ts-node --transpile-only scripts/some-script.ts --help

The argument parser will print the following:

some-script.ts - works wonders

Usage: some-script.ts <eventCode> [ -f -y <year> ]

[jtdevos]

Hey Jim, this is great. In my mind it's a big improvement over the built-in parseArgs because it allows for more config info (e.g. description) and makes the process for accessing values similar regardless if they are named or positional arguments.

I guess my only comment is that your excellent write-up of this is relegated to this pull-request. I know that we are relatively anti jsdoc here, but might be nice to capture the descriptions & examples from your PR into the reportUtils.ts file.

[jimlerza]

Hey Jim, this is great. In my mind it's a big improvement over the built-in parseArgs because it allows for more config info (e.g. description) and makes the process for accessing values similar regardless if they are named or positional arguments.

I guess my only comment is that your excellent write-up of this is relegated to this pull-request. I know that we are relatively anti jsdoc here, but might be nice to capture the descriptions & examples from your PR into the reportUtils.ts file.

Great points!

I have added more JSDoc to the types and I have also created a readme for the argument parser (which is basically just the content from this PR description, reworded to be less salesy).

[En-8]

😍