@boost/args

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

• https://boostlib.dev/docs/args
• https://boostlib.dev/api/args

Index

Classes

• ParseError
• ValidationError

Functions

• format
• parse
• parseInContext

Interfaces

• Arg
• Arguments
• Category
• Command
• Config
• Flag
• MultipleOption
• Option
• Param
• ParserOptions
• ParserSettings
• SingleOption

Type Aliases

• AliasMap
• ArgList
• ArgsErrorCode
• Argv
• CommandChecker
• ContextFactory
• InferArgType
• InferOptionConfig
• InferParamConfig
• ListType
• LongOptionName
• MapOptionConfig
• MapParamConfig
• MapParamType
• OptionConfig
• OptionConfigMap
• OptionMap
• ParamConfig
• ParamConfigList
• PrimitiveType
• ScalarType
• ShortOptionName
• UnknownOptionMap
• ValueType

Variables

• ArgsError
• COMMAND_FORMAT
• DEFAULT_BOOLEAN_VALUE
• DEFAULT_NUMBER_VALUE
• DEFAULT_STRING_VALUE
• LONG_OPTION_FORMAT
• OPTION_LIKE
• SHORT_OPTION_FORMAT
• SHORT_OPTION_GROUP_FORMAT

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

• T: PrimitiveType[]

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

• T: PrimitiveType[]

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 = ...