Skip to main content

Module: @sapphire/decorators

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, CommandOptions } from '@sapphire/framework';
import type { Message } from 'discord.js';

(at)ApplyOptions<CommandOptions>({
description: 'ping pong',
enabled: true
})
export class UserCommand extends Command {
public async messageRun(message: Message) {
const msg = await message.channel.send('Ping?');

return msg.edit(
`Pong! Client Latency ${Math.round(this.context.client.ws.ping)}ms. API Latency ${msg.createdTimestamp - message.createdTimestamp}ms.`
);
}
}

Type parameters

NameType
Textends PieceOptions

Parameters

NameType
optionsOrFnT | (context: PieceContext) => T

Returns

ClassDecorator

Defined in

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


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:36


RequiresClientPermissions

โ–ธ Const 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

โ–ธ Const 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


enumerable

โ–ธ Const enumerable(value): (target: unknown, key: string) => void

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

deprecated Use @Enumerable instead. The lowercased decorator will be removed in the next major version of @sapphire/decorators

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:30


enumerableMethod

โ–ธ Const enumerableMethod(value): MethodDecorator

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

deprecated Use @EnumerableMethod instead. The lowercased decorator will be removed in the next major version of @sapphire/decorators

Parameters

NameTypeDescription
valuebooleanWhether the method should be enumerable or not

Returns

MethodDecorator

Defined in

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