Command Halts

Command halts are functions that are executed when a command, such as the context menu, message, or slash command, is terminated, cooled-down, or fails to execute.

There are different types of command halts that serves their own purposes.

Command Halt Data Types

• CommandErrorHaltTriggerData Used to handle error thrown by the command.
• CommandCooldownHaltTriggerData Used to handle commands that are cooled-down.
• CommandPreconditionResultHaltTriggerData Used to handle a command that has triggered a precondition.
• CommandInvalidArgumentsHaltTriggerData Can only be used with message commands to handle invalid argument error.
• CommandMissingArgumentsHaltTriggerData Can only be used with message commands to handle missing argument error.
• CommandInvalidFlagsHaltTriggerData Can only be used with message commands to handle invalid flag error.
• CommandMissingFlagsHaltTriggerData Can only be used with message commands to handle missing flag error.

Command halts are identified using the .reason property that uses the CommandHaltReason enum.

To create a command halt, create a new file in a folder that is NOT your modules folder. In this case we will use ./modules/halts/error-handler.js. Inside that file export the command halt data.

import { CommandHaltReason, CommandType } from 'reciple';

export class MyErrorCommandHalt {
    id = 'my.errorhandler';
    disabled = false; // Defaults to false when not defined

    errorMessage =  `An error occured while executing this command`;

    contextMenuCommandHalt(data) {
        if (data.reason !== CommandHaltReason.Error) return;

        const interaction = data.executeData.interaction;
        if (interaction.replied || interaction.deferred) {
            await interaction.editReply(this.errorMessage);
        } else {
            await interaction.reply(this.errorMessage);
        }

        return true;
    }

    messageCommandHalt(data) {
        if (data.reason !== CommandHaltReason.Error) return;

        await data.executeData.message.reply(this.errorMessage);
        return true;
    }

    slashCommandHalt(data) {
        if (data.reason !== CommandHaltReason.Error) return;

        const interaction = data.executeData.interaction;
        if (interaction.replied || interaction.deferred) {
            await interaction.editReply(this.errorMessage);
        } else {
            await interaction.reply(this.errorMessage);
        }

        return true;
    }
};

contextMenuCommandHalt, messageCommandHalt, and slashCommandHalt are the functions that will handle the command halt.

• Return true if the halt is handled
• false|string|Error if it fails
• null|undefined to pass the command halt trigger to the next command halt.

Learn more about command halt data structure. View Docs

Global Scope Command Halt

To use the command halt that we made, you can import it in your config file and add it to the commandHalts array.

import { MyErrorHandler } from './modules/halts/error-handler.js';

export const config = {
    /// ...other config...
    commandHalts: [
        new MyErrorHandler()
    ]
};

Command Scope Command Halt

Alternatively, you can add it to a single command using the .addHalts() or .setHalts() methods.

import { SlashCommandBuilder } from 'reciple';
import { MyErrorHandler } from '../halts/error-handler.js';

new SlashCommandBuilder()
    .setName('ping')
    .setDescription('Pong command')
    .setPreconditions(new MyErrorHandler())
    .setExecute(async ({ interaction }) => {
        await interaction.reply('Pong!');
    })

Now, when a command fails, the code above will send a message rather than terminating the bot process.

An error occured while executing this command

You can disable a global or command scope halts from a command using .addDisabledHalts() or .setDisabledHalts(). Just pass the id of the halt you want to disable to the arguments of this method to not use them.

Set Global Command Halt In Module

This methods allows you to set a global command halt within a module without adding it to the config file.

import { MyErrorHandler } from '../halts/error-handler.js';

export class LoadHalt {
    halt = new MyErrorHandler();

    async onStart({ client }) {
        client.commands.addHalts(this.halt);

        return true;
    }
}

export default LoadHalt;