Command options

Options can be declared within a command, with four types available:

• StringOption: Returns a string.
• NumberOption: Returns a number.
• BooleanOption: Returns a boolean.
• MentionOption: Returns the BaseUser who was mentioned.

Note

As command options are received as strings, in number options, that string is parsed into a number. If it couldn’t be parsed (for example, if the string isn’t a valid number representation), it will return NaN.

Note

Boolean options return a boolean. They return true if the option was specified without a value. If a value is specified, it will attempt to parse it into a boolean. If there isn’t any defaultValue and the value couldn’t be parsed, it will return null.

Tip

Mention options return a BaseUser. If multiple users were specified, it will return null. If only one user was mentioned, but there is another character before or after it, it will also return null.

You can use grouped options to get an array of users mentioned in that option if you want the user to specify more than one user in the command.

import { MentionOption } from '@twitchfy/chatbot';

const option = new MentionOption({ grouped: true });

Command options work with this template:

!command -option1 value1 -option2 value2

Tip

You can change your option operator within ChatBotOptions optionOperator option.

Attach options into commands

To attach options to commands, the only thing we must do is set the options field within our command class.

TypeScript

commands/dice.ts

import {
    ChatCommand,
    SetCommand,
    NumberOption
} from '@twitchfy/chatbot';

const options = {
    min: new NumberOption({ defaultValue: 1 }),
    max: new NumberOption({ defaultValue: 6 })
};

@SetCommand({
    name: 'dice',
    options
})

export default class DiceCommand extends ChatCommand {};

JavaScript

commands/dice.js

const {
    ChatCommand,
    NumberOption
} = require('@twitchfy/chatbot');

const options = {
    min: new NumberOption({ defaultValue: 1 }),
    max: new NumberOption({ defaultValue: 6 })
};

module.exports = class DiceCommand extends ChatCommand {
    name = 'dice';
    options = options;
};

As seen in the example above, we are defining the options as an object whose keys are the option names. We are setting a defaultValue to the option, which will be returned if the option is not specified. If there isn’t a default value and the option isn’t specified, it will return null.

Running commands with options

Running commands with options is similar to running a normal command, but the CommandContext includes an options object containing all of the options defined for the command.

Note

In TypeScript you will have to set the first generic type of TwitchContext with the typeof your options for the context to be typed.

TypeScript

commands/dice.ts

import {
    ChatCommand,
    SetCommand,
    NumberOption,
    type TwitchContext
} from '@twitchfy/chatbot';

const options = {
    min: new NumberOption({ defaultValue: 1 }),
    max: new NumberOption({ defaultValue: 6 })
};

@SetCommand({
    name: 'dice',
    options
})

export default class DiceCommand extends ChatCommand {
    async run(ctx: TwitchContext<typeof options>){

        const { min, max } = ctx.options;

        return await ctx.reply(`The dice has rolled. And the number is... ${this.generateValue(min, max)}`)

    }

    generateValue(min: number, max: number){
        return Math.floor(Math.random() * (max - min + 1)) + min;
    }
};

JavaScript

commands/dice.js

const {
    ChatCommand,
    NumberOption
} = require('@twitchfy/chatbot');

const options = {
    min: new NumberOption({ defaultValue: 1 }),
    max: new NumberOption({ defaultValue: 6 })
};

module.exports = class DiceCommand extends ChatCommand {
    name = 'dice';
    options = options;
    async run(ctx){

        const { min, max } = ctx.options;

        return await ctx.reply(`The dice has rolled. And the number is... ${this.generateValue(min, max)}`)

    }

    generateValue(min, max){
        return Math.floor(Math.random() * (max - min + 1)) + min;
    }

};