@sapphire/decorators 7.0.0-pr-601.2f2c308a.0 → 7.0.0-pr-935.7da5c8bb

package/dist/cjs/index.d.cts

@@ -0,0 +1,503 @@
+import { PermissionResolvable, SlashCommandBuilder, SlashCommandSubcommandsOnlyBuilder, SlashCommandOptionsOnlyBuilder, ContextMenuCommandBuilder } from 'discord.js';
+import { Piece, Command, ApplicationCommandRegistryRegisterOptions } from '@sapphire/framework';
+import { Container } from '@sapphire/pieces';
+
+/**
+ * Decorator that sets the enumerable property of a class field to the desired value.
+ * @param value Whether the property should be enumerable or not
+ */
+declare function Enumerable(value: boolean): (target: object, key: string) => void;
+/**
+ * Decorator that sets the enumerable property of a class method to the desired value.
+ * @param value Whether the method should be enumerable or not
+ */
+declare function EnumerableMethod(value: boolean): MethodDecorator;
+
+/**
+ * The function precondition interface.
+ */
+interface FunctionPrecondition {
+    /**
+     * The arguments passed to the function or class' method.
+     */
+    (...args: any[]): boolean | Promise<boolean>;
+}
+/**
+ * The fallback interface, this is called when the function precondition returns or resolves with a falsy value.
+ */
+interface FunctionFallback {
+    /**
+     * The arguments passed to the function or class' method.
+     */
+    (...args: any[]): unknown;
+}
+/**
+ * Utility to make a method decorator with lighter syntax and inferred types.
+ *
+ * ```typescript
+ * // Enumerable function
+ *	function enumerableMethod(value: boolean) {
+ *		return createMethodDecorator((_target, _propertyKey, descriptor) => {
+ *			descriptor.enumerable = value;
+ *		});
+ *	}
+ * ```
+ * @param fn The method to decorate
+ */
+declare function createMethodDecorator(fn: MethodDecorator): MethodDecorator;
+/**
+ * Utility to make a class decorator with lighter syntax and inferred types.
+ * @param fn The class to decorate
+ * @see {@link ApplyOptions}
+ */
+declare function createClassDecorator<TFunction extends (...args: any[]) => void>(fn: TFunction): ClassDecorator;
+/**
+ * Utility to make function preconditions.
+ *
+ * ```typescript
+ * // 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
+ * @param precondition The function that defines whether or not the function should be run, returning the returned value from fallback
+ * @param fallback The fallback value that defines what the method should return in case the precondition fails
+ */
+declare function createFunctionPrecondition(precondition: FunctionPrecondition, fallback?: FunctionFallback): MethodDecorator;
+/**
+ * Creates a new proxy to efficiently add properties to class without creating subclasses
+ * @param target The constructor of the class to modify
+ * @param handler The handler function to modify the constructor behavior for the target
+ * @hidden
+ */
+declare function createProxy<T extends object>(target: T, handler: Omit<ProxyHandler<T>, 'get'>): T;
+
+declare enum DecoratorIdentifiers {
+    RequiresClientPermissionsGuildOnly = "requiresClientPermissionsGuildOnly",
+    RequiresClientPermissionsMissingPermissions = "requiresClientPermissionsMissingPermissions",
+    RequiresUserPermissionsGuildOnly = "requiresUserPermissionsGuildOnly",
+    RequiresUserPermissionsMissingPermissions = "requiresUserPermissionsMissingPermissions"
+}
+/**
+ * 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 {@link RequiresUserPermissions}
+ * @remark This decorator makes the decorated function asynchronous, so any result should be `await`ed.
+ * @param permissionsResolvable Permissions that the method should have.
+ * @example
+ * ```typescript
+ * 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!');
+ * 	}
+ * }
+ * ```
+ */
+declare const RequiresClientPermissions: (...permissionsResolvable: PermissionResolvable[]) => 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 {@link RequiresClientPermissions}
+ * @remark This decorator makes the decorated function asynchronous, so any result should be `await`ed.
+ * @param permissionsResolvable Permissions that the method should have.
+ * @example
+ * ```typescript
+ * 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!');
+ * 	}
+ * }
+ * ```
+ */
+declare const RequiresUserPermissions: (...permissionsResolvable: PermissionResolvable[]) => MethodDecorator;
+/**
+ * Requires the message to be run in a guild context, this decorator requires the first argument to be a {@link Message} or {@link BaseInteraction} instance which includes all interaction types
+ * @since 1.0.0
+ * @param fallback The fallback value passed to {@link createFunctionPrecondition}
+ */
+declare function RequiresGuildContext(fallback?: FunctionFallback): MethodDecorator;
+/**
+ * Requires the message to be run in a dm context, this decorator requires the first argument to be a {@link Message} or {@link BaseInteraction} instance which includes all interaction types
+ * @since 1.0.0
+ * @param fallback The fallback value passed to {@link createFunctionPrecondition}
+ */
+declare function RequiresDMContext(fallback?: FunctionFallback): MethodDecorator;
+
+/**
+ * Decorator function that applies given options to any Sapphire piece
+ * @param optionsOrFn The options or function that returns options to pass to the piece constructor
+ * @example
+ * ```typescript
+ * 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
+ * ```typescript
+ * 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
+ *   }
+ * }
+ * ```
+ */
+declare function ApplyOptions<T extends Piece.Options>(optionsOrFn: T | ((parameters: ApplyOptionsCallbackParameters) => T)): ClassDecorator;
+/**
+ * Decorator for registering chat input command.
+ * @param optionsFn The function that returns options to pass to the registry.
+ * @example
+ * ```typescript
+ * import { RegisterChatInputCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ *
+ * (at)RegisterChatInputCommand((builder, command) => builder
+ *   .setName(command.name)
+ *   .setDescription(command.description)
+ * )
+ * export class UserCommand extends Command {
+ * 	 public override chatInputRun(interaction: Command.ChatInputCommandInteraction) {
+ * 	   	return interaction.reply({ content: 'HI!' });
+ * 	 }
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterChatInputCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ *
+ * (at)RegisterChatInputCommand((builder, command) => builder
+ *		.setName(command.name)
+ *		.setDescription(command.description),
+ *	{
+ *		idHints: ['737141877803057244'],
+ *		guildIds: ['737141877803057244']
+ *	}
+ * )
+ * export class UserCommand extends Command {
+ * 	 public override chatInputRun(interaction: Command.ChatInputCommandInteraction) {
+ * 	   	return interaction.reply({ content: 'HI!' });
+ * 	 }
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterChatInputCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ *
+ * (at)RegisterChatInputCommand((builder) => builder
+ *   .setName('hi')
+ *   .setDescription('Sends a hi message')
+ * )
+ * export class UserCommand extends Command {
+ * 	 public override chatInputRun(interaction: Command.ChatInputCommandInteraction) {
+ * 	   	return interaction.reply({ content: 'HI!' });
+ * 	 }
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { ApplyOptions, RegisterChatInputCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import type { Message } from 'discord.js';
+ *
+ * (at)ApplyOptions<Command.Options>({
+ *   description: 'ping pong',
+ *   enabled: true
+ * })
+ * (at)RegisterChatInputCommand((builder, command) => builder
+ *   .setName(command.name)
+ *   .setDescription(command.description)
+ * )
+ * export class UserCommand extends Command { *
+ * 	 public override chatInputRun(interaction: Command.ChatInputCommandInteraction) {
+ * 	   	return interaction.reply({ content: 'HI!' });
+ * 	 }
+ * }
+ * ```
+ */
+declare function RegisterChatInputCommand<CMD extends Command = Command>(optionsFn: ChatInputCommandDecoratorsMap<CMD>['optionsFn'], registryOptions?: ApplicationCommandRegistryRegisterOptions): ClassDecorator;
+/**
+ * Decorator for registering message context menu command.
+ * @param optionsFn The function that returns options to pass to the registry.
+ * @example
+ * ```typescript
+ * import { RegisterMessageContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type MessageContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterMessageContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterMessageContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type MessageContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterMessageContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall),
+ *	{
+ *		idHints: ['737141877803057244'],
+ *		guildIds: ['737141877803057244']
+ *	}
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterMessageContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type MessageContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterMessageContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterMessageContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type MessageContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterMessageContextMenuCommand((builder) => builder
+ * 	 .setName('Send HI')
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { ApplyOptions, RegisterMessageContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type MessageContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)ApplyOptions<Command.Options>({
+ *   enabled: true
+ * })
+ * (at)RegisterMessageContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ */
+declare function RegisterMessageContextMenuCommand<CMD extends Command = Command>(optionsFn: ContextMenuCommandDecoratorsMap<CMD>['optionsFn'], registryOptions?: ApplicationCommandRegistryRegisterOptions): ClassDecorator;
+/**
+ * Decorator for registering user context menu command.
+ * @param optionsFn The function that returns options to pass to the registry.
+ * @example
+ * ```typescript
+ * import { RegisterUserContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type UserContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterUserContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: UserContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterUserContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type MessageContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterUserContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall),
+ *	{
+ *		idHints: ['737141877803057244'],
+ *		guildIds: ['737141877803057244']
+ *	}
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { RegisterUserContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type UserContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)RegisterUserContextMenuCommand((builder, command) => builder
+ * 	 .setName('Send HI')
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: UserContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: `HI ${interaction.targetUser}!` })
+ * 	}
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * import { ApplyOptions, RegisterUserContextMenuCommand } from '@sapphire/decorators';
+ * import { Command } from '@sapphire/framework';
+ * import { ApplicationIntegrationType, InteractionContextType, type UserContextMenuCommandInteraction } from 'discord.js';
+ *
+ * (at)ApplyOptions<Command.Options>({
+ *   enabled: true
+ * })
+ * (at)RegisterUserContextMenuCommand((builder, command) => builder
+ * 	 .setName(command.name)
+ * 	 .setContexts(InteractionContextType.Guild)
+ * 	 .setIntegrationTypes(ApplicationIntegrationType.GuildInstall)
+ * )
+ * export class UserCommand extends Command {
+ * 	public override contextMenuRun(interaction: MessageContextMenuCommandInteraction) {
+ * 		return interaction.reply({ content: 'HI!' })
+ * 	}
+ * }
+ * ```
+ */
+declare function RegisterUserContextMenuCommand<CMD extends Command = Command>(optionsFn: ContextMenuCommandDecoratorsMap<CMD>['optionsFn'], registryOptions?: ApplicationCommandRegistryRegisterOptions): ClassDecorator;
+interface ApplyOptionsCallbackParameters {
+    container: Container;
+    context: Piece.LoaderContext;
+}
+interface ChatInputCommandDecoratorsMap<CMD extends Command> {
+    type: 'RegisterChatInputCommand';
+    optionsFn: (builder: SlashCommandBuilder, command: ThisType<CMD> & CMD) => SlashCommandBuilder | SlashCommandSubcommandsOnlyBuilder | SlashCommandOptionsOnlyBuilder;
+    registryOptions?: ApplicationCommandRegistryRegisterOptions;
+}
+interface ContextMenuCommandDecoratorsMap<CMD extends Command> {
+    type: 'RegisterMessageContextMenuCommand' | 'RegisterUserContextMenuCommand';
+    optionsFn: (builder: ContextMenuCommandBuilder, //
+    command: ThisType<CMD> & CMD) => ContextMenuCommandBuilder;
+    registryOptions?: ApplicationCommandRegistryRegisterOptions;
+}
+
+export { ApplyOptions, type ApplyOptionsCallbackParameters, DecoratorIdentifiers, Enumerable, EnumerableMethod, type FunctionFallback, type FunctionPrecondition, RegisterChatInputCommand, RegisterMessageContextMenuCommand, RegisterUserContextMenuCommand, RequiresClientPermissions, RequiresDMContext, RequiresGuildContext, RequiresUserPermissions, createClassDecorator, createFunctionPrecondition, createMethodDecorator, createProxy };