Options and Inputs

Configuring Options

When registering a option, you can configure its option name, alias, description, and validators, which Mustard supports in the form of parameter lists or objects:

import { Validator } from "mustard-cli/validator";

@Command('run')
class RunCommandHandle implements CommandStruct {
  @Option('message')
  @Option('message', 'm')
  @Option('message', 'message option')
  @Option('message', 'm', 'message option')
  @Option('message', Validator.Required().String().MinLength(5))
  @Option({
    name: 'message',
    alias: 'm',
    description: 'message option',
    validator: Validator.Required().String().MinLength(5)
  })
  private messageOption: string = 'message default value';

  public run() {}
}

• To split @Option('message', 'm') and @Option('message', 'message option') overloads, if you provide a string which length is less than 3, it will be treated as alias, otherwise it will be treated as description.

Property messageOption will be parsed as --message or -m option, and its default value is message default value.

Variadic Options

Mustard supports variadic option by @VariadicOption decorator, it will parse all the rest of the command line arguments into an array. And, it can be configured just like @Option decorator except validator:

@Command('run')
class RunCommandHandle implements CommandStruct {
  @VariadicOption('projects')
  @VariadicOption('projects', 'p')
  @VariadicOption('projects', 'projects to handle')
  @VariadicOption('projects', 'p', 'projects to handle')
  @VariadicOption({
    name: 'projects',
    alias: 'p',
    description: 'projects to handle',
  })
  private pprojectsToHandle: string[] = [];

  public run() {}
}

Property pprojectsToHandle will be parsed as --projects or -p option, and its default value is [].

$ node index.js run --projects=project1 project2 project3
$ node index.js run --projects=project1 --project=project2 --project=project3

• Mustard will use different cli arguments parser libraries depending on the situation, when there's no variadic option and no option alias provided, it will use yargs-parser as cli arguments parser , otherwise mri will be used for performance improvement.

Validator

Mustard provide simple validator by Zod, you can use it from Validator namespace.

import { Validator } from "mustard-cli/validator";

Validator.Required().String().MinLength(5);
Validator.Required().String().StartsWith('node-');
Validator.Number().Int();
Validator.Boolean();


enum ValidSource {}

Validator.Optional().Enum(ValidSource)

Restrict Values

type Templates  = 'foo' | 'bar';

@Command('run')
class RunCommand implements CommandStruct {
  
  @Option()
  template: Template = 'foo';

  public run() {}
}

In command registration above, when we execute command like bin run --template=baz, Mustard doesnot validate if it's from pre-defined valid values, and we cannot add validation from @Validator.Enum().

But this can be a common suitation that we'd like to ensure valid user input for some options:

• If we received 'foo' or 'bar', use it;
• If we received undefined, use the default value;
• If we received any unexpected value, use the default value;

Decorator @Restrict should help in such cases:

const templates = ['foo', 'bar'] as const;

type RestrictTemplates = typeof templates[number];

@Command('run')
class RunCommand implements CommandStruct {
  
  @Option()
  @Restrict(templates)
  template: RestrictTemplates = 'foo';

  public run() {}
}

Usage:

@Restrict(/* Expected values for this property */)

• When restrictValues was specified as array, we need to ensure the provided value was included by it.
• When restrictValues was an object(Enum usually), we need to ensure the provided value was included in all of its values;