@thisismanta/pessimist
Version:
This is a Node.js library that helps derive `process.argv` into a first-hand-**TypeScript** value-strict object with very minimal configurations.
188 lines (149 loc) • 3.72 kB
Markdown
This is a Node.js library that helps derive `process.argv` into a first-hand-**TypeScript** value-strict object with very minimal configurations.
```js
import { parseArguments } from '@thisismanta/pessimist'
const {
// Types are derived from the default values supplied below
count, dryRun, outputFile,
...positionalArguments
} = parseArguments(process.argv.slice(2),
{
// Define your all possible arguments and their default values here
count: 0,
dryRun: false,
outputFile: '',
exclude: [] as string[],
},
{
// Forward -d to --dryRun (optional)
aliases: { d: 'dryRun' },
// Disallow both --dryRun and --outputFile to be supplied at the same time
exclusives: [['dryRun', 'outputFile']],
}
)
for (const item of Array.from(positionalArguments)) {
// Consume your positional argument here
}
```
```sh
--count=3 -d --output-file-name=file3 file1 file2
```
The above example results in the below object:
```js
{
// From the named arguments
count: 3,
dryRun: true,
outputFile: 'file3',
// From the positional arguments
'0': 'file1',
'1': 'file2',
length: 2,
// From the default values
exclude: [],
}
```
## Rejecting unknown arguments
The below command argument exits with **non-zero code** because `somethingElse` is **not defined** in the default object (the second parameter of `parseArguments` function).
```sh
--something-else
# Error: Unexpected an unknown argument: --something-else
```
⚠️ Therefore it is **important** to have all the possible arguments defined in the default object.
## Auto converting argument names from _dash-case_ to _camelCase_
The below command arguments are the same because `dry-run` is transformed into a camel case.
```sh
--dryRun # { dryRun: true }
--dry-run # { dryRun: true }
```
## Auto converting false-like values
```sh
--dryRun=false # { dryRun: false }
--dryRun=False
--dryRun=FALSE
--dryRun=n
--dryRun=no
--dryRun=0
```
## Auto negating through `no` name prefix
Having `no` argument prefix negates the Boolean value.
```sh
--noDryRun # { dryRun: false }
--no-dry-run # { dryRun: false }
--no-dry-run=false # { dryRun: true }
```
Having `no` argument prefix clears the string value.
```sh
--noOutputFile # { outputFile: '' }
--no-output-file # { outputFile: '' }
```
Having `no` argument prefix for an array removes the given value from the output array.
```sh
--exclude=file1 --exclude=file2 --no-exclude=file1
# { exclude: ['file2'] }
```
## Auto removing duplicate values
```sh
--exclude=file1 --exclude=file2 --exclude=file1
# { input: ['file2', 'file1'] }
```
Notice that `'file1'` comes after `'file2'` because it appears on the rightmost in the argument.
## Supporting name aliases
```js
parseArguments(
process.argv.slice(2),
{
dryRun: false
},
{
aliases: {
d: 'dryRun',
commit: '!dryRun'
}
}
)
```
```sh
--dryRun # { dryRun: true }
-d # { dryRun: true }
```
However, the below command arguments yield the opposite because of the `!` operator defined in `commit` alias above.
```sh
--commit # { dryRun: false }
--noCommit # { dryRun: true }
--no-commit # { dryRun: true }
```
## Supporting single-letter short-hand arguments
```js
parseArguments(
process.argv.slice(2),
{
verbose: false,
f: false,
},
{
aliases: {
v: 'verbose',
}
}
)
```
```sh
-vf # { verbose: true, f: true }
```
## Rejecting mutual exclusive names
```js
parseArguments(
process.argv.slice(2),
{
dryRun: false,
commit: true,
},
{
exclusives: [['dryRun', 'commit'], ...],
}
)
```
```sh
--dryRun --commit
# Error: Unexpected mutual exclusive arguments: --dryRun --commit
```