README.md

Arge

A tiny package to parse CLI flags and arguments into an object.

Installation

yarn add arge

# or
npm i arge

Usage

const { arge } = require('arge')

// or
import { arge } from 'arge'

Then:

const args = arge(process.argv)

This will return arguments parsed from process.argv like this:

node app.js --dry-run --mode=development --test=false --retries=100

...into an object similar to below:

{
  "dryRun": true,
  "mode": "development",
  "test": false,
  "retries": 100
}

Typescript

For type safety, arge will accept a generic for typing the resulting object.

Example

const { foo, bar } = arge(process.argv)

In the above scenario, foo and bar will report the following:

Property 'foo' does not exist on type 'unknown'

Property 'bar' does not exist on type 'unknown'

To address this, we can apply a generic:

interface Args {
  foo: string
  bar: number
}

const { foo, bar } = arge<Args>(process.argv)

API

arge(flags, options?)

Returns a key-value pairs object of flags

flags

Type: string[]

options

Type: object | undefined

isArgv

Type: boolean

Default: true

By default, the arge function assumes that you have passed process.argv. It does this because:

The first element will be process.execPath.

The second element will be the path to the JavaScript file being executed

https://nodejs.org/docs/latest/api/process.html#processargv

This package will omit those two items from the output.

If you wanted to pass an arbitrary array of flags that don't come from process.argv, you can set this option to false.

For example

const flags = [
  '--dry-run',
  '--mode=development',
  '--test=false',
  '--retries=100',
]

const args = arge(flags, { isArgv: false })

This would then output:

{
  "dryRun": true,
  "mode": "development",
  "test": false,
  "retries": 100
}

camelCaseKeys

Type: boolean

Default: true

This converts hyphen separated keys into camel case. To prevent this behaviour, you can set this value to false.

const flags = ['--dry-run']

const args = arge(flags, { camelCaseKeys: false })

This would then output:

{
  "dry-run": true
}