Module: @sapphire/decorators
Enumerations
Interfaces
Functions
ApplyOptions
▸ ApplyOptions<T>(optionsOrFn): ClassDecorator
Decorator function that applies given options to any Sapphire piece
Type parameters
| Name | Type |
|---|---|
T | extends PieceOptions |
Parameters
| Name | Type |
|---|---|
optionsOrFn | T | (parameters: ApplyOptionsCallbackParameters) => T |
Returns
ClassDecorator
Example
import { ApplyOptions } from '@sapphire/decorators';
import { Command } from '@sapphire/framework';
import type { Message } from 'discord.js';
@ApplyOptions<Command.Options>({
description: 'ping pong',
enabled: true
})
export class UserCommand extends Command {
public override async messageRun(message: Message) {
const msg = await message.channel.send('Ping?');
return msg.edit(
`Pong! Client Latency ${Math.round(this.container.client.ws.ping)}ms. API Latency ${msg.createdTimestamp - message.createdTimestamp}ms.`
);
}
}
Example
import { ApplyOptions } from '@sapphire/decorators';
import { Listener } from '@sapphire/framework';
import { GatewayDispatchEvents, GatewayMessageDeleteDispatch } from 'discord.js';
@ApplyOptions<Listener.Options>(({ container }) => ({
description: 'Handle Raw Message Delete events',
emitter: container.client.ws,
event: GatewayDispatchEvents.MessageDelete
}))
export class UserListener extends Listener {
public override run(data: GatewayMessageDeleteDispatch['d']): void {
if (!data.guild_id) return;
const guild = this.container.client.guilds.cache.get(data.guild_id);
if (!guild || !guild.channels.cache.has(data.channel_id)) return;
// Do something with the data
}
}
Defined in
Enumerable
▸ Enumerable(value): (target: unknown, key: string) => void
Decorator that sets the enumerable property of a class field to the desired value.
Parameters
| Name | Type | Description |
|---|---|---|
value | boolean | Whether the property should be enumerable or not |
Returns
fn
▸ (target, key): void
Parameters
| Name | Type |
|---|---|
target | unknown |
key | string |
Returns
void
Defined in
EnumerableMethod
▸ EnumerableMethod(value): MethodDecorator
Decorator that sets the enumerable property of a class method to the desired value.
Parameters
| Name | Type | Description |
|---|---|---|
value | boolean | Whether the method should be enumerable or not |
Returns
MethodDecorator
Defined in
RequiresClientPermissions
▸ RequiresClientPermissions(...permissionsResolvable): MethodDecorator
Allows you to set permissions required for individual methods. This is particularly useful for subcommands that require specific permissions.
Parameters
| Name | Type | Description |
|---|---|---|
...permissionsResolvable | PermissionResolvable[] | Permissions that the method should have. |
Returns
MethodDecorator
Remark
This decorator applies to the client that is to execute the command. For setting permissions required user of the command see RequiresUserPermissions
Remark
This decorator makes the decorated function asynchronous, so any result should be awaited.
Example
import { ApplyOptions, RequiresClientPermissions } from '@sapphire/decorators';
import { Subcommand } from '@sapphire/plugin-subcommands';
import type { Message } from 'discord.js';
(at)ApplyOptions<Subcommand.Options>({
aliases: ['cws'],
description: 'A basic command with some subcommands',
subCommands: ['add', 'remove', 'reset', { input: 'show', default: true }]
})
export default class extends Subcommand {
// Anyone should be able to view the result, but not modify
public async show(message: Message) {
return message.channel.send('Showing!');
}
(at)RequiresClientPermissions('BAN_MEMBERS') // This subcommand requires the client to be able to ban members.
public async add(message: Message) {
return message.channel.send('Adding!');
}
(at)RequiresClientPermissions('BAN_MEMBERS') // This subcommand requires the client to be able to ban members.
public async remove(message: Message) {
return message.channel.send('Removing!');
}
(at)RequiresClientPermissions('BAN_MEMBERS') // This subcommand requires the client to be able to ban members.
public async reset(message: Message) {
return message.channel.send('Resetting!');
}
}
Defined in
RequiresDMContext
▸ RequiresDMContext(fallback?): MethodDecorator
Requires the message to be run in a dm context, this decorator requires the first argument to be a Message instance
Parameters
| Name | Type | Description |
|---|---|---|
fallback | FunctionFallback | The fallback value passed to createFunctionInhibitor |
Returns
MethodDecorator
Since
1.0.0
Defined in
RequiresGuildContext
▸ RequiresGuildContext(fallback?): MethodDecorator
Requires the message to be run in a guild context, this decorator requires the first argument to be a Message instance
Parameters
| Name | Type | Description |
|---|---|---|
fallback | FunctionFallback | The fallback value passed to createFunctionInhibitor |
Returns
MethodDecorator
Since
1.0.0
Defined in
RequiresUserPermissions
▸ RequiresUserPermissions(...permissionsResolvable): MethodDecorator
Allows you to set permissions required for individual methods. This is particularly useful for subcommands that require specific permissions.
Parameters
| Name | Type | Description |
|---|---|---|
...permissionsResolvable | PermissionResolvable[] | Permissions that the method should have. |
Returns
MethodDecorator
Remark
This decorator applies to the user of the command. For setting permissions required for the client see RequiresClientPermissions
Remark
This decorator makes the decorated function asynchronous, so any result should be awaited.
Example
import { ApplyOptions, RequiresUserPermissions } from '@sapphire/decorators';
import { Subcommand } from '@sapphire/plugin-subcommands';
import type { Message } from 'discord.js';
(at)ApplyOptions<Subcommand.Options>({
aliases: ['cws'],
description: 'A basic command with some subcommands',
subCommands: ['add', 'remove', 'reset', { input: 'show', default: true }]
})
export default class extends Subcommand {
// Anyone should be able to view the result, but not modify
public async show(message: Message) {
return message.channel.send('Showing!');
}
(at)RequiresUserPermissions('BAN_MEMBERS') // This subcommand requires the user of the command to be able to ban members.
public async add(message: Message) {
return message.channel.send('Adding!');
}
(at)RequiresUserPermissions('BAN_MEMBERS') // This subcommand requires the user of the command to be able to ban members.
public async remove(message: Message) {
return message.channel.send('Removing!');
}
(at)RequiresUserPermissions('BAN_MEMBERS') // This subcommand requires the user of the command to be able to ban members.
public async reset(message: Message) {
return message.channel.send('Resetting!');
}
}
Defined in
createClassDecorator
▸ createClassDecorator<TFunction>(fn): ClassDecorator
Utility to make a class decorator with lighter syntax and inferred types.
Type parameters
| Name | Type |
|---|---|
TFunction | extends (...args: any[]) => void |
Parameters
| Name | Type | Description |
|---|---|---|
fn | TFunction | The class to decorate |
Returns
ClassDecorator
See
Defined in
createFunctionPrecondition
▸ createFunctionPrecondition(precondition, fallback?): MethodDecorator
Utility to make function preconditions.
// No fallback (returns undefined)
function requireGuild(value: number) {
return createFunctionPrecondition((message: Message) =>
message.guild !== null
);
}
// With fallback
function requireGuild(
value: number,
fallback: () => unknown = () => undefined
) {
return createFunctionPrecondition(
(message: Message) => message.guild !== null,
fallback
);
}
Parameters
| Name | Type | Description |
|---|---|---|
precondition | FunctionPrecondition | The function that defines whether or not the function should be run, returning the returned value from fallback |
fallback | FunctionFallback | The fallback value that defines what the method should return in case the precondition fails |
Returns
MethodDecorator
Since
1.0.0
Defined in
createMethodDecorator
▸ createMethodDecorator(fn): MethodDecorator
Utility to make a method decorator with lighter syntax and inferred types.
// Enumerable function
function enumerableMethod(value: boolean) {
return createMethodDecorator((_target, _propertyKey, descriptor) => {
descriptor.enumerable = value;
});
}
Parameters
| Name | Type | Description |
|---|---|---|
fn | MethodDecorator | The method to decorate |
Returns
MethodDecorator