stagas/decarg

decorator based cli arguments parser

decarg

decorator based cli arguments parser

npm i decarg

pnpm add decarg

yarn add decarg

Examples

# basic

# view source

example/basic.ts

import { arg, decarg } from 'decarg'

class Options {
  @arg('<file> [<file>, decarg.]', 'Files to process') file!: string[]

  @arg('--', '[decarg.rest]', 'The rest of the arguments') passArgs = []

  @arg('-f', '--flag', 'Flag about something') flag = false

  @arg('-c', '--count', 'How many times') count = 42

  @arg('-C', 'Choose color', ['blue', 'red', 'yellow']) color = 'blue'

  @arg('-s', '--string', 'Some string') string = 'hmm'

  @arg('--meh', 'Meh') meh: string[] = []

  static examples = {
    '-f foo': 'Convert foo by force',
    '-f foo -s': 'Convert foo by force smoothly',
  }
}

const options = decarg(new Options())

// these fail:

// const options = decarg(new Options(), ['exec'])
// const options = decarg(new Options(), ['exec', '-C'])
// const options = decarg(new Options(), ['exec', '-C=green'])
// const options = decarg(new Options(), ['exec', '-c=not a number'])

// this passes:

// const options = decarg(new Options(), ['exec', 'foo'])

console.log(options)

API

# OptionExpectedValueError

src/errors.ts#L20

# constructor(option)

src/errors.ts#L22

# new OptionExpectedValueError()

OptionExpectedValueError<T>

# option

Option<T>

# option

src/errors.ts#L21

Option<T>

# prepareStackTrace

# (err, stackTraces)

# err

Error

# stackTraces

CallSite []

(err, stackTraces)  =>

any

# stackTraceLimit

number

# captureStackTrace(targetObject, constructorOpt)

# targetObject

object

# constructorOpt

Function

captureStackTrace(targetObject, constructorOpt)  =>

void

# OptionHelpRequested

src/errors.ts#L49

# constructor(options)

src/errors.ts#L50

# new OptionHelpRequested()

OptionHelpRequested<T>

# options

Options<T>

# prepareStackTrace

# (err, stackTraces)

# err

Error

# stackTraces

CallSite []

(err, stackTraces)  =>

any

# stackTraceLimit

number

# captureStackTrace(targetObject, constructorOpt)

# targetObject

object

# constructorOpt

Function

captureStackTrace(targetObject, constructorOpt)  =>

void

# OptionInvalidValueError

src/errors.ts#L35

# constructor(option, value)

src/errors.ts#L37

# new OptionInvalidValueError()

OptionInvalidValueError<T>

# option

Option<T>

# value

unknown

# option

src/errors.ts#L36

Option<T>

# prepareStackTrace

# (err, stackTraces)

# err

Error

# stackTraces

CallSite []

(err, stackTraces)  =>

any

# stackTraceLimit

number

# captureStackTrace(targetObject, constructorOpt)

# targetObject

object

# constructorOpt

Function

captureStackTrace(targetObject, constructorOpt)  =>

void

# OptionValidationError

src/errors.ts#L8

# constructor(message)

src/errors.ts#L9

# new OptionValidationError()

OptionValidationError

# message

string

# prepareStackTrace

# (err, stackTraces)

# err

Error

# stackTraces

CallSite []

(err, stackTraces)  =>

any

# stackTraceLimit

number

# captureStackTrace(targetObject, constructorOpt)

# targetObject

object

# constructorOpt

Function

captureStackTrace(targetObject, constructorOpt)  =>

void

# arg(description)

src/arg.ts#L7

# description

ArgDescription

arg(description)  =>

{
# target

Function

(target)  =>

void
# target

Object

# propertyKey

string | symbol

(target, propertyKey)  =>

void
}

# decarg(target, argv, { exit, log })

src/index.ts#L17

# target

T

# argv  =  ...

string []

# overrides  =  {}

{

# exit

undefined |

# (code)

# code

number

(code)  =>

never

# log

undefined | {

# data

any []

(data)  =>

void
# data

any []

(data)  =>

void
# message

any

# optionalParams

any []

(message, optionalParams)  =>

void
}

}

decarg<T>(target, argv, { exit, log })  =>

undefined | T

# parse(target, argv)

src/parse.ts#L17

# target

T

# argv  =  ...

string []

parse<T>(target, argv)  =>

T

Credits

• reflect-metadata by Ron Buckton – Polyfill for Metadata Reflection API

Contributing

Fork or edit and submit a PR.

All contributions are welcome!

License

MIT © 2022 stagas