Skip to content

Latest commit

 

History

History
203 lines (135 loc) · 3.09 KB

README.md

File metadata and controls

203 lines (135 loc) · 3.09 KB

@hypernym/args

A fast and ultra lightweight CLI argument parser.

Repository | Package | Releases | Discussions

pnpm add @hypernym/args

Features

  • TypeScript friendly
  • Fully tree-shakeable
  • No dependencies

Parser

Arguments

Unprefixed inputs are stored in an array.

$ arg

# => { _: ['arg'] }
$ arg-a arg-b arg-c

# => { _: ['arg-a', 'arg-b', 'arg-c'] }

Flags

Inputs with -- prefix are parsed as flags.

By default, standalone flags with no value are defined as true.

$ --flag

# => { _: [], flag: true, }
$ --flag value

# => { _: [], flag: 'value', }
$ --flag=value

# => { _: [], flag: 'value', }

Aliases

Inputs with - prefix are parsed as aliases.

By default, standalone aliases with no value are defined as true.

$ -alias

# => { _: [], alias: true, }
$ -alias value

# => { _: [], alias: 'value', }
$ -alias=value

# => { _: [], alias: 'value', }

Ignores

  • Ignores standalone inputs -- and -
  • Ignores argument inputs that include =
$ arg=value -- arg-b=value -

# => { _: [] }

Usage

$ hello world --foo bar -baz -cli demo --fuz
import { createArgs } from '@hypernym/args'

interface Args {
  foo?: string
  baz?: boolean
  cli?: string
  fuz?: boolean
}

const args = createArgs<Args>()

console.log(args)

/*
{
  _: ['hello', 'world'],
  foo: 'bar',
  baz: true,
  cli: 'demo',
  fuz: true
}
*/

Options

argv

Specifies an array of values to parse as arguments.

  • Type: string[] | undefined
  • Default: process.argv.slice(2)
import { createArgs } from '@hypernym/args'

createArgs({
  argv: process.argv.slice(2),
})

alias

Specifies an object of alias that will be added to the parsed output with matching values.

  • Type: Record<string, string | string[]> | undefined
  • Default: undefined
import { createArgs } from '@hypernym/args'

createArgs({
  alias: {
    config: ['conf', 'c'],
    help: 'h',
  },
})

defaults

Specifies an object of defaults that will be added to the parsed output regardless of CLI inputs.

  • Type: (Record<string, unknown> & { _?: string[] }) | undefined
  • Default: undefined
import { createArgs } from '@hypernym/args'

createArgs({
  defaults: {
    _: ['value'],
    a: true,
  },
})

exclude

Specifies an array of values that will be skipped when parsing arguments.

  • Type: string[] | undefined
  • Default: undefined
import { createArgs } from '@hypernym/args'

createArgs({
  exclude: ['arg', '--flag', '-alias'],
})

Community

Feel free to ask questions or share new ideas.

Use the official discussions to get involved.

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.