`ts
const sharedParams = startChain()
.addParam(param.flag(['-h', '--help'], 'help'))
.addParam(param.flag(['-v', '--verbose'], 'verbose'))
.addParam(param.string(['-u', '--url'], 'url'));

const downloadParams = sharedParams.addParam(
param.string(['-d', '--destination'], 'destination'),
);

const uploadParams = sharedParams.addParam(
param.string(['-s', '--source'], 'source'),
);

switch (process.argv[2]) {
case 'upload': {
const {help = false, verbose = false, source, url} = parse(
downloadParams,
process.argv.slice(3),
).extract();
if (help) return printUploadHelp();
upload(source, url, {verbose});
}
case 'download': {
const {help = false, verbose = false, destination, url} = parse(
uploadParams,
process.argv.slice(3),
).extract();
if (help) return printDownloadHelp();
download(url, destination, {verbose});
}
default: {
if (process.argv.includes('-h') || process.argv.includes('--help')) {
printUploadHelp();
printDownloadhelp();
process.exit(0);
} else {
console.error(
Unrecognised command "${process.argv[2]}". Pass --help to print usage.,
);
}
}
}

function printUploadHelp() {
console.log(Usage: api upload --source file.txt --url http://example.com

Parameters:

-h --help Print this help text.
-v --verbose Output extra logs for debugging
-u --url The url to fetch from
-d --destionation Where to save the file);
}

function printDownloadHelp() {
console.log(Usage: api download --destination file.txt --url http://example.com

Parameters:

-h --help Print this help text.
-v --verbose Output extra logs for debugging
-u --url The url to fetch from
-d --destionation Where to save the file);
}
`

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain()
.addParam(param.flag(['-r', '--recursive'], 'recursive'))
.addParam(param.flag(['-f', '--force'], 'force'))
.addParam(param.flag(['-v', '--verbose'], 'verbose'));

const {recursive = false, force = false, verbose = false} = parse(
params,
process.argv.slice(2),
).extract();
`

`

run --recursive -f -v

`

Flags are true or false values, if not present they default to undefined.

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain()
.addParam(param.string(['-m', '--message'], 'message'))
.addParam(param.string(['-f', '--from'], 'from'));

const {message = 'hello world', from = 'Me'} = parse(
params,
process.argv.slice(2),
).extract();

console.log(${message} from ${from});
`

Strings can be any arbitrary string of text that immediately follows the configured keys. An erorr is returned if the same parameter is passed multiple times (see stringList).

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain().addParam(
param.stringList(['-m', '--messages'], 'messages'),
);

const {messages = []} = parse(params, process.argv.slice(2)).extract();

for (const m of messages) {
console.log(m);
}
`

`
run -m "Hello" -m "World"
`

A string list is just like a string, but can occur multiple times to form a list. If the parameter only occurs once, the result is an array with one element.

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain().addParam(
param.enumString(['-l', '--level'], 'level', [
'info',
'warn',
'error',
] as const),
);

const {level = 'error'} = parse(params, process.argv.slice(2)).extract();

if (level === 'info') {
console.info('Some info');
}
if (level === 'info' || 'warn') {
console.warn('Some warning');
}
console.warn('Some error');
`

`
run -l warn
`

An enum string can only have one of a defined list of values.

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain().addParam(param.integer(['-v', '--value'], 'value'));

const {value = 0} = parse(params, process.argv.slice(2)).extract();

console.log(value * 2);
`

`
run -v 21
`

An integer is any positive or negative whole number between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain()
.addParam(param.positionalString('message'))
.addParam(param.positionalString('to'));

const {message = 'Hello', to: 'My Friend'} = parse(params, process.argv.slice(2)).extract();

console.log(I just want to say ${message} to ${to});
`

`
run "so many important things" "all the people who need to hear it"
`

A positional string is a string that does not require any "key" to indicate its location. They are parsed in the order they appear in within the chain. Non-positional parameters can appear in any location, including before or after the positional parameters. Positional strings cannot start with "-"

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain()
.addParam(param.string(['--to'], 'to'))
.addParam(param.string(['--from'], 'from'))
.addParam(param.positionalStringList('messages'));

const {
messages = [],
to = 'My Friend',
from = 'Anonymous',
} = parse(params, process.argv.slice(2)).extract();

console.log(Dear ${to},);
for (const message of messages) {
console.log(message);
}
console.log(Sincerely ${from});
``

`
run "I do not always" --from Forbes "think in order" --to Anyone
`

A positional string list consumes all strings that don't start with - and are not consumed by any other parser. Since it consumes so eagerly, there is rarely any point having 2 positional string list parsers.

> N.B. if you have any positionalString parsers, they must go before your positionalStringList parser.

`ts
import {startChain, param, parse} from 'parameter-reducers';

const params = startChain().addParam(
param.positionalEnumString('env', ['staging', 'production'] as const),
);

const {env = 'staging'} = parse(params, process.argv.slice(2)).extract();

if (env === 'staging') {
console.info('Deploying to staging');
}
if (env === 'production') {
console.warn('Deploying to production');
}
`

`
run production
`

A positional enum string can only have one of a defined list of values.

`ts
import {startChain, param, parse, valid, invalid} from 'parameter-reducers';

const params = startChain()
.addParam(
param.parsedString(['--url'], 'url', (value) => {
try {
return valid(new URL(value));
} catch (ex) {
return invalid(${value} is not a valid URL.);
}
}),
)
.addParam(
param.parsedString(['--env'], 'env', (value) => {
if (['staging', 'production'].includes(value)) {
return valid(value);
} else {
return invalid(
${value} is not a valid environment ("staging" or "production").,
);
}
}),
);

const {url = new URL('http://example.com'), environment = 'staging'} = parse(
params,
process.argv.slice(2),
).extract();

load(url.href, {environment});
`

`
run --url "http://example.com" --env production
`

parsedString is the basis used for the integer parameter type. It allows you to perform arbitrary validation and convert the string input to a new type of your choosing.

`ts
import {startChain, param, parse, valid, invalid} from 'parameter-reducers';

const params = startChain()
.addParam(
param.parsedStringList(['--urls'], 'urls', (value) => {
try {
return valid(new URL(value));
} catch (ex) {
return invalid(${value} is not a valid URL.);
}
}),
)
.addParam(
param.parsedString(['--env'], 'env', (value) => {
if (['staging', 'production'].includes(value)) {
return valid(value);
} else {
return invalid(
${value} is not a valid environment ("staging" or "production").,
);
}
}),
);

const {urls = [], environment = 'staging'} = parse(
params,
process.argv.slice(2),
).extract();

for (const url of urls) {
load(url.href, {environment});
}
`

`
run --url "http://example.com/foo" --url "http://example.com/bar" --env production
`

parsedStringList combines the parsing from parsedString with the ability to pass multiple values like stringList.

`ts
import {startChain, param, parse, valid, invalid} from 'parameter-reducers';

const params = startChain()
.addParam(
param.parsedPositionalString('url', (value) => {
try {
return valid(new URL(value));
} catch (ex) {
return undefined;
}
}),
)
.addParam(
param.parsedPositionalString('env', (value) => {
if (['staging', 'production'].includes(value)) {
return valid(value);
} else {
return invalid(${value} is not a valid URL or environment.);
}
}),
);

const {url = new URL('http://example.com'), environment = 'staging'} = parse(
params,
process.argv.slice(2),
).extract();

load(url.href, {environment});
`

`
run "http://example.com/bar" production
-- or equivalently:
run production "http://example.com/bar"
`

parsedPositionalString allows you to validate/parse positional parameters. If you return undefined, the parser will continue looking for other matches. This means that if you have validation rules that are mutually exclusive, you could have the parameters be passed in any order. If you return invalid, the parser stops there and reports the error.

`ts
import {startChain, param, parse, valid, invalid} from 'parameter-reducers';

const params = startChain()
.addParam(
param.parsedString(['--env'], 'env', (value) => {
if (['staging', 'production'].includes(value)) {
return valid(value);
} else {
return invalid(${value} is not a valid environment.);
}
}),
)
.addParam(
param.parsedPositionalStringList('urls', (value) => {
if (value[0] === '-') return undefined;
try {
return valid(new URL(value));
} catch (ex) {
return invalid(${value} is not a valid URL.);
}
}),
);

const {urls = [], environment = 'staging'} = parse(
params,
process.argv.slice(2),
).extract();

for (const url of urls) {
load(url.href, {environment});
}
`

`
run "http://example.com/foo" "http://example.com/bar" --env production
`

parsedPositionalStringList allows you to validate/parse multiple positional parameters. By default, it will stop to check for any other paremeter matches after each parameter is found. If you prefer it to consume as many parameters as possible, you can pass {eager: true}.

`ts
import {startChain, param, parse, valid, invalid} from 'parameter-reducers';

// input is the remaining list of un-parsed parameters (i.e. an array of strings)
// parsed is an object containing all the parameteres we've seen/parsed so far
const params = startChain().addParam<{dirname: string}>((input, parsed) => {
const str = input[0];

if (str[0] === '-') {
return undefined;
}

if ('dirname' in parsed) {
return invalid(You cannot specify multiple directories.);
}

if (!statSync(str).isDirectory()) {
return invalid(${str} is not a valid directory.);
}

// for custom parsers, a valid result needs
// 1. the previously parsed input
// 2. the newly parsed input
// 3. the remaining, un-parsed parameters
return valid(parsed, {dirname: str}, input.slice(1));
});

const {dirname = process.cwd()} = parse(
params,
process.argv.slice(2),
).extract();

console.log(readdirSync(dirname));
`