declargs is a minimal, declarative, TypeScript-first command-line argument parser library.
There are many, many JavaScript command-line argument parsers out there: arg, argparse, args, caporal, clap, command-line-args, commander, dashdash, getopts, meow, minimist, mri, optimist, optionator, sade, yargs-parser, yargs, ...
However, none of them fit my particular need:
- Isomorphic: No Node.js-specific APIs must be used
- Work on exotic, old JS runtimes (e.g. Rhino): No use of
setTimeout(), promises, orasync/await - Can generate a help message
- Infer correct type signature of the parsed options
This is why I built declargs.
declargs is a native ESM-only package. Sorry, CommonJS!
import declargs from "declargs";
const parser = declargs({
name: "helloworld",
options: {
foo: {
description: "This is foo",
alias: ["f"],
},
"say-hello": {
description: 'When given, the program will say "Hello".',
default: false,
type: "boolean",
},
},
});
// In Node.js...
const options = parser.parse(process.argv.slice(2));
// In browser...
const options = parser.parse("-f something --say-hello");declargs works best with object literals. It uses the type information to build a correct shape for the output:
// Will pass type tests
const foo = options.foo;
const f = options.f;
const sayHello = options["say-hello"];
const rest = options._;
// Will fail in TypeScript
const bar = options.bar;declargs exports a single factory function: declargs(cfg).
Factory function for the parser. Returns the created parser object.
Name of the script. Used in the "Usage" section of the generated help text.
An object that maps each command line option to its option config object.
Each option config object looks like this:
interface OptionConfig {
// Required. A string that describes the option.
description: string;
// Optional. Array of aliases for this option.
alias?: string[];
// Optional. Default value for this option if it is omitted.
// Note that a 'string' type option must be given a string value, and a
// 'boolean' type option must be given a boolean value.
default?: boolean | number | string;
// Optional. A string constant that forces the parser to treat the option
// value as a boolean or string.
// (There is no constant for 'number')
type?: "boolean" | "string";
}Parses a command line string or an array of string tokens and returns an object containing the parsed options.
Alised options will expose every alias as the property of the returned object.
Any non-option tokens are returned inside the special _ property.
A string containing the command line, or an array of strings.
If you use process.argv, you must slice it yourself before passing it to declargs.
Returns a formatted help message as a string.
const parser = declargs({
name: "helloworld",
options: {
foo: {
description: "This is foo",
alias: ["f"],
},
"say-hello": {
description: 'When given, the program will say "Hello".',
default: false,
type: "boolean",
},
},
});
console.log(parser.generateHelp());Will give:
Usage
helloworld [options]
Options
--foo, -f This is foo
--say-hello, --hello, -s The program will say "Hello". (default: false)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent