Skip to main content

@boost/args

Build Status npm version npm deps

A convention based argument parsing and formatting library, with strict validation checks. It is not a command line interface.

import { parse } from '@boost/args';
interface Options {    help: boolean;    logLevel: 'info' | 'error' | 'warn';    version: boolean;}
const { command, errors, options, params, rest } = parse<Options>(process.argv.slice(2), {    commands: ['build', 'install', 'update'],    options: {        help: {            default: false,            description: 'Show a help menu',            type: 'boolean',            short: 'H',        },        logLevel: {            choices: ['info', 'error', 'warn'],            default: 'info',            description: 'Customize logging level',        },        version: {            default: false,            description: 'Show the version number',            type: 'boolean',            short: 'V',        },    },});

Features#

  • Commands and sub-commands: cmd, cmd:sub
  • Options (long and short) that set a value(s): --foo value, --foo=value, -f value, -f=value
    • Camel (preferred) or kebab cased option names.
  • Flags (boolean options) that take no value: --bar, -B
    • With implicit negation support: --no-bar
  • Parameters that act as standalone values: foo bar baz
    • Can be marked as required.
  • Rest arguments that are passed to subsequent scripts (aggregated after --): foo -- bar
  • Supports string, number, boolean, and list based values, with the addition of:
    • Single value based on a list of possible choices.
    • Multiple values with optional arity count requirements.
  • Group multiple short options under a single argument: -fBp
    • Increment a counter each time a short option is found in a group.
  • Strict parser and validation checks, allowing for informative interfaces.
    • Custom option and param validation for increased accuracy.

Installation#

yarn add @boost/args

Documentation#

Index

Type aliases

AliasMap

AliasMap: Record<string, string>

ArgList

ArgList: string[]

ArgsErrorCode

ArgsErrorCode: keyof typeof errors

Argv

Argv: string[]

CommandChecker

CommandChecker: (arg: string) => boolean

ContextFactory

ContextFactory: (arg: string, argv: Argv) => ParserOptions<{}> | undefined

InferArgType

InferArgType<T>: T extends boolean ? boolean : T extends number[] | number ? number : string

Type parameters

  • T

InferOptionConfig

InferOptionConfig<T>: T extends boolean ? Flag : T extends number[] | string[] ? MultipleOption<T> : T extends number | string ? SingleOption<T> : never

Determine option based on type.


Type parameters

  • T

InferParamConfig

InferParamConfig<T>: T extends PrimitiveType ? Param<T> : never

Determine option based on type. Only primitives are allowed.


Type parameters

  • T

ListType

ListType: number[] | string[]

LongOptionName

LongOptionName: string

Option name without leading “–”.

MapOptionConfig

MapOptionConfig<T>: { [ K in keyof T ]: InferOptionConfig<T[K]> }

Type parameters

  • T: object

MapParamConfig

MapParamConfig<T>: T extends [infer A, infer B, infer C, infer D, infer E] ? [InferParamConfig<A>, InferParamConfig<B>, InferParamConfig<C>, InferParamConfig<D>, InferParamConfig<E>] : T extends [infer A, infer B, infer C, infer D] ? [InferParamConfig<A>, InferParamConfig<B>, InferParamConfig<C>, InferParamConfig<D>] : T extends [infer A, infer B, infer C] ? [InferParamConfig<A>, InferParamConfig<B>, InferParamConfig<C>] : T extends [infer A, infer B] ? [InferParamConfig<A>, InferParamConfig<B>] : T extends [infer A] ? [InferParamConfig<A>] : T extends ArgList ? Param<string>[] : never

Type parameters

MapParamType

MapParamType<T>: T extends [infer A, infer B, infer C, infer D, infer E] ? [A, B, C, D, E, ...ArgList] : T extends [infer A, infer B, infer C, infer D] ? [A, B, C, D, ...ArgList] : T extends [infer A, infer B, infer C] ? [A, B, C, ...ArgList] : T extends [infer A, infer B] ? [A, B, ...ArgList] : T extends [infer A] ? [A, ...ArgList] : T extends ArgList ? ArgList : never

Type parameters

OptionConfig

OptionConfig: Option<any> & { arity?: number; choices?: PrimitiveType[]; count?: boolean; default?: ValueType; multiple?: boolean }

Abstract type for easier typing.

OptionConfigMap

OptionConfigMap: Record<string, OptionConfig>

OptionMap

OptionMap: Record<string, ValueType>

ParamConfig

ParamConfig: Param<any>

Abstract type for easier typing.

ParamConfigList

ParamConfigList: ParamConfig[]

PrimitiveType

PrimitiveType: ScalarType | boolean

ScalarType

ScalarType: number | string

ShortOptionName

ShortOptionName: A | a | B | b | C | c | D | d | E | e | F | f | G | g | H | h | I | i | J | j | K | k | L | l | M | m | N | n | O | o | P | p | Q | q | R | r | S | s | T | t | U | u | V | v | W | w | X | x | Y | y | Z | z

Short option name without leading “-“.

UnknownOptionMap

UnknownOptionMap: Record<string, string>

ValueType

ValueType: ListType | PrimitiveType

Variables

constArgsError

ArgsError: new (code: COMMAND_INVALID_FORMAT | COMMAND_NOT_FIRST | COMMAND_PROVIDED | CONTEXT_REQUIRED | GROUP_REQUIRED_COUNT | GROUP_UNSUPPORTED_TYPE | OPTION_INVALID_COUNT_TYPE | OPTION_UNKNOWN | OPTION_UNKNOWN_FORMAT | OPTION_UNKNOWN_MORE | PARAM_INVALID_ORDER | PARAM_REQUIRED | PARAM_REQUIRED_NO_DEFAULT | PARAM_UNKNOWN | SHORT_DEFINED | SHORT_INVALID_CHAR | SHORT_UNKNOWN | VALUE_INVALID_ARITY | VALUE_INVALID_CHOICE | VALUE_INVALID_FORMAT | VALUE_NO_INLINE | VALUE_NON_ARRAY | VALUE_NON_BOOL | VALUE_NON_NUMBER | VALUE_NON_STRING, params?: unknown[]) => Error & ScopedError<COMMAND_INVALID_FORMAT | COMMAND_NOT_FIRST | COMMAND_PROVIDED | CONTEXT_REQUIRED | GROUP_REQUIRED_COUNT | GROUP_UNSUPPORTED_TYPE | OPTION_INVALID_COUNT_TYPE | OPTION_UNKNOWN | OPTION_UNKNOWN_FORMAT | OPTION_UNKNOWN_MORE | PARAM_INVALID_ORDER | PARAM_REQUIRED | PARAM_REQUIRED_NO_DEFAULT | PARAM_UNKNOWN | SHORT_DEFINED | SHORT_INVALID_CHAR | SHORT_UNKNOWN | VALUE_INVALID_ARITY | VALUE_INVALID_CHOICE | VALUE_INVALID_FORMAT | VALUE_NO_INLINE | VALUE_NON_ARRAY | VALUE_NON_BOOL | VALUE_NON_NUMBER | VALUE_NON_STRING> = ...

constCOMMAND_FORMAT

COMMAND_FORMAT: RegExp = ...

constDEFAULT_BOOLEAN_VALUE

DEFAULT_BOOLEAN_VALUE: false = false

constDEFAULT_NUMBER_VALUE

DEFAULT_NUMBER_VALUE: 0 = 0

constDEFAULT_STRING_VALUE

DEFAULT_STRING_VALUE: = ''

constLONG_OPTION_FORMAT

LONG_OPTION_FORMAT: RegExp = ...

constOPTION_LIKE

OPTION_LIKE: RegExp = ...

constSHORT_OPTION_FORMAT

SHORT_OPTION_FORMAT: RegExp = ...

constSHORT_OPTION_GROUP_FORMAT

SHORT_OPTION_GROUP_FORMAT: RegExp = ...