Defining commands

Caution

To avoid confusing bugs or errors, make sure to look at type safety!

Commands are defined using decorators.

Centurion has four decorators:

• @Register - Classes containing commands must be decorated with this to be registered. You can also register groups from here.
• @Command - Used to define commands
• @Group - Used to assign groups to a command
• @Guard - Used to assign guards to a command

A command can be defined like so:

@Register()
class EchoCommand {
    @Command({
        name: "echo",
        description: "Displays text",
        arguments: [
            {
                name: "text",
                description: "The text to display",
                type: CenturionType.String,
            },
        ],
    })
    echo(ctx: CommandContext, text: string) {
        ctx.reply(text);
    }
}

Command context

Each command is passed a CommandContext as its first argument.

The primary purpose of a CommandContext is to send a response back to the command executor.

@Command({ name: "hello" })
hello(ctx: CommandContext) {
    ctx.reply(`Hello, ${ctx.executor.Name}!`);
}

@Command({ name: "error" })
errorMessage(ctx: CommandContext) {
    // The default interface supports rich text, so it can be used here
    ctx.error("An <b>error</b> occurred.");
}

It also contains data such as the command executor and the text used to execute the command.

@Command({ name: "echo" })
echo(ctx: CommandContext) {
    print(`${ctx.executor.Name} executed: ${ctx.text}`);
}

Type safety

Type safety can only be provided if the types for your arguments match your parameters’ types.

It’s worth keeping in mind that no warning or error will be displayed for argument and parameter types that do not match.

To avoid confusing bugs or errors, you should exercise caution when defining command arguments and ensure they have the correct type.

For example, the following code would not be type-safe - the argument types and parameter types don’t match!

@Command({
    name: "echo",
    description: "Displays text",
    arguments: [
        {
            name: "text",
            description: "The text to display",
            type: CenturionType.String, // We're requesting a string for this argument...
        },
    ],
})
echo(ctx: CommandContext, text: number) {} // But we're expecting a number here!

In order to assert that the argument and parameter types are equal, we would need a way to retrieve each parameter’s type. Unfortunately, this is not possible without using a TypeScript transformer. There are no plans to implement this currently, as it would require manual configuration and add a significant maintenance cost to the project.