Skip to main content

Module: decorators/src

Enumerations

Interfaces

Functions

ApplyOptions

ApplyOptions<T>(optionsOrFn): ClassDecorator

Decorator function that applies given options to any Sapphire piece

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-api-types/v9';

@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
}
}

Type parameters

NameType
Textends PieceOptions

Parameters

NameType
optionsOrFnT | (parameters: ApplyOptionsCallbackParameters) => T

Returns

ClassDecorator

Defined in

projects/utilities/packages/decorators/src/piece-decorators.ts:52


Enumerable

Enumerable(value): (target: unknown, key: string) => void

Decorator that sets the enumerable property of a class field to the desired value.

Parameters

NameTypeDescription
valuebooleanWhether the property should be enumerable or not

Returns

fn

▸ (target, key): void

Parameters
NameType
targetunknown
keystring
Returns

void

Defined in

projects/utilities/packages/decorators/src/base-decorators.ts:8


EnumerableMethod

EnumerableMethod(value): MethodDecorator

Decorator that sets the enumerable property of a class method to the desired value.

Parameters

NameTypeDescription
valuebooleanWhether the method should be enumerable or not

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/base-decorators.ts:28


RequiresClientPermissions

RequiresClientPermissions(...permissionsResolvable): MethodDecorator

Allows you to set permissions required for individual methods. This is particularly useful for subcommands that require specific permissions.

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 { SubCommandPluginCommand, SubCommandPluginCommandOptions } from '@sapphire/plugin-subcommands';
import type { Message } from 'discord.js';

(at)ApplyOptions<SubCommandPluginCommandOptions>({
aliases: ['cws'],
description: 'A basic command with some subcommands',
subCommands: ['add', 'remove', 'reset', { input: 'show', default: true }]
})
export default class extends SubCommandPluginCommand {
// 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!');
}
}

Parameters

NameTypeDescription
...permissionsResolvablePermissionResolvable[]Permissions that the method should have.

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/djs-decorators.ts:79


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

since 1.0.0

Parameters

NameTypeDescription
fallbackFunctionFallbackThe fallback value passed to createFunctionInhibitor

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/djs-decorators.ts:192


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

since 1.0.0

Parameters

NameTypeDescription
fallbackFunctionFallbackThe fallback value passed to createFunctionInhibitor

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/djs-decorators.ts:183


RequiresUserPermissions

RequiresUserPermissions(...permissionsResolvable): MethodDecorator

Allows you to set permissions required for individual methods. This is particularly useful for subcommands that require specific permissions.

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 { SubCommandPluginCommand, SubCommandPluginCommandOptions } from '@sapphire/plugin-subcommands';
import type { Message } from 'discord.js';

(at)ApplyOptions<SubCommandPluginCommandOptions>({
aliases: ['cws'],
description: 'A basic command with some subcommands',
subCommands: ['add', 'remove', 'reset', { input: 'show', default: true }]
})
export default class extends SubCommandPluginCommand {
// 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!');
}
}

Parameters

NameTypeDescription
...permissionsResolvablePermissionResolvable[]Permissions that the method should have.

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/djs-decorators.ts:148


createClassDecorator

createClassDecorator<TFunction>(fn): ClassDecorator

Utility to make a class decorator with lighter syntax and inferred types.

see ApplyOptions

Type parameters

NameType
TFunctionextends (...args: any[]) => void

Parameters

NameTypeDescription
fnTFunctionThe class to decorate

Returns

ClassDecorator

Defined in

projects/utilities/packages/decorators/src/utils.ts:43


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
);
}

since 1.0.0

Parameters

NameTypeDescription
preconditionFunctionPreconditionThe function that defines whether or not the function should be run, returning the returned value from fallback
fallbackFunctionFallbackThe fallback value that defines what the method should return in case the precondition fails

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/utils.ts:73


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

NameTypeDescription
fnMethodDecoratorThe method to decorate

Returns

MethodDecorator

Defined in

projects/utilities/packages/decorators/src/utils.ts:34