options

options

Options are named parameters with values that are passed to a command.

Usage

Options are passed as an array of objects, with each object containing the properties of the option.

{
  options: [
    {
      name: 'name',
      type: 'string',
      description: 'The name of the user',
      required: true
    }
  ]
}

Multiple Values

Multiple values can be passed to an option by setting the multiple property to true.

{
  options: [
    {
      name: 'category',
      type: 'string',
      description: 'The category or categories of the item',
      multiple: true
    }
  ]
}

In this scenario, --category one --category two and --category one two would both be stored as ['one', 'two'].

Default Values

Default values can be set for options by providing a value for the default property.

{
  options: [
    {
      name: 'name',
      type: 'string',
      description: 'The name of the user',
      default: 'John Doe'
    }
  ]
}

In this scenario, if the user does not provide a value for --name, the value will default to 'John Doe'.

Validation

Options can be validated by providing a function to the validate property.

{
  options: [
    {
      name: 'name',
      type: 'string',
      description: 'The name of the user',
      validate: (v) => v.length > 0
    }
  ]
}

In this scenario, the value of --name must be a string with a length greater than 0.

Properties

Property	Required	Type(s)	Default	Description
name	Y	string		Option name
alias	N	string		Short alias
type	N	string/function	string	Value type
description	N	string		Description
required	N	boolean	false	Required flag
multiple	N	boolean	false	Multiple flag
default	N	any		Default value
tags	N	string/array		Tag(s) to apply in details
global	N	boolean	false	Global flag
itemName	N	string		Item name in --help menu
validate	N	function		Function to validate value

name: string
alias?: string
type?: any
description?: string
required?: boolean
multiple?: boolean
default?: any
tags?: string | string[]
global?: boolean
itemName?: string
validate?: (v) => Promise<boolean>

name

The name of the option. This is the key that the value will be stored under in the command data object.

{
  options: [
    {
      name: 'name'
    }
  ]
}

alias

A short alias for the option. This can be used in place of the full name.

{
  options: [
    {
      name: 'name',
      alias: 'n'
    }
  ]
}

In this scenario, --name and -n would be interchangeable.

type

The type of the option. This can be a string or a function. If a function is provided, it will be used to parse the value. Default is string.

Common values for type include:

• string
• number
• boolean
• array
• object

{
  options: [
    {
      name: 'name',
      type: 'string'
    }
  ]
}

{
  options: [
    {
      name: 'name',
      type: (v) => v.toUpperCase()
    }
  ]
}

description

A description of the option. This is used in the help menu to describe the option to the user.

{
  options: [
    {
      name: 'name',
      description: 'The name of the user'
    }
  ]
}

required

A flag to indicate if the option is required. If set to true, the option must be provided by the user.

{
  options: [
    {
      name: 'name',
      required: true
    }
  ]
}

multiple

A flag to indicate if the option can accept multiple values. If set to true, the option will be stored as an array of values.

{
  options: [
    {
      name: 'category',
      multiple: true
    }
  ]
}

In this scenario, --category one --category two and --category one two would both be stored as ['one', 'two'].

default

A default value for the option. If the user does not provide a value, the default value will be used.

{
  options: [
    {
      name: 'name',
      default: 'John Doe'
    }
  ]
}

tags

Tag(s) to apply to the option in the details object.

{
  options: [
    {
      name: 'name',
      tags: 'tag'
    }
  ]
}

{
  options: [
    {
      name: 'name',
      tags: ['tag1', 'tag2']
    }
  ]
}

global

A flag to indicate if the option is global. Global options are available to all subcommands.

Note: Global option functionality is not yet implemented.

{
  options: [
    {
      name: 'name',
      global: true
    }
  ]
}

itemName

The name of the option to display in the --help menu.

{
  options: [
    {
      name: 'name',
      itemName: 'Name'
    }
  ]
}

validate

A function to validate the value of the option. The function should return a boolean value indicating if the value is valid.

{
  options: [
    {
      name: 'name',
      validate: (v) => v.length > 0
    }
  ]
}

In this scenario, the value of --name must be a string with a length greater than 0.

Examples

Basic Usage

new Command({
  options: [
    {
      name: 'name',
      type: 'string',
      description: 'The name of the user',
      required: true
    },
    {
      name: 'age',
      type: 'number',
      description: 'The age of the user',
      default: 18
    },
    {
      name: 'category',
      type: 'string',
      description: 'The category or categories of the item',
      multiple: true
    }
  ],
  action: async (data) => console.log(data)
})

$ my-command --name John --age 25 --category one two
{
  name: 'John',
  age: 25,
  category: ['one', 'two']
}