refactor: Split message send/edit types/documentation (#8590)

* refactor: split message send/edit types

* refactor: move `MessageEditOptions`

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
This commit is contained in:
Jiralite
2022-09-11 19:22:53 +01:00
committed by GitHub
parent 32523325c6
commit 8e1afaebdb
10 changed files with 106 additions and 112 deletions

View File

@@ -32,7 +32,7 @@ class WebhookClient extends BaseClient {
/**
* Options for a webhook client.
* @typedef {Object} WebhookClientOptions
* @property {MessageMentionOptions} [allowedMentions] Default value for {@link WebhookMessageOptions#allowedMentions}
* @property {MessageMentionOptions} [allowedMentions] Default value for {@link BaseMessageOptions#allowedMentions}
* @property {RESTOptions} [rest] Options for the REST manager
*/
@@ -68,7 +68,7 @@ class WebhookClient extends BaseClient {
/* eslint-disable no-empty-function, valid-jsdoc */
/**
* Sends a message with this webhook.
* @param {string|MessagePayload|WebhookMessageOptions} options The content for the reply
* @param {string|MessagePayload|WebhookCreateMessageOptions} options The content for the reply
* @returns {Promise<APIMessage>}
*/
send() {}

View File

@@ -147,6 +147,15 @@ class MessageManager extends CachedManager {
* @returns {?Snowflake}
*/
/**
* Options that can be passed to edit a message.
* @typedef {BaseMessageOptions} MessageEditOptions
* @property {Array<JSONEncodable<AttachmentPayload>>} [attachments] An array of attachments to keep,
* all attachments will be kept if omitted
* @property {MessageFlags} [flags] Which flags to set for the message
* <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
*/
/**
* Edits a message, even if it's not cached.
* @param {MessageResolvable} message The message to edit

View File

@@ -105,7 +105,7 @@ class UserManager extends CachedManager {
/**
* Sends a message to a user.
* @param {UserResolvable} user The UserResolvable to identify
* @param {string|MessagePayload|MessageOptions} options The options to provide
* @param {string|MessagePayload|MessageCreateOptions} options The options to provide
* @returns {Promise<Message>}
*/
async send(user, options) {

View File

@@ -644,22 +644,6 @@ class Message extends Base {
);
}
/**
* Options that can be passed into {@link Message#edit}.
* @typedef {Object} MessageEditOptions
* @property {?string} [content] Content to be edited
* @property {Embed[]|APIEmbed[]} [embeds] Embeds to be added/edited
* @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
* @property {MessageFlags} [flags] Which flags to set for the message
* <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
* @property {Attachment[]} [attachments] An array of attachments to keep,
* all attachments will be kept if omitted
* @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
* Files to add to the message
* @property {ActionRow[]|ActionRowOptions[]} [components]
* Action rows containing interactive components for the message (buttons, select menus)
*/
/**
* Edits the content of the message.
* @param {string|MessagePayload|MessageEditOptions} options The options to provide
@@ -770,7 +754,8 @@ class Message extends Base {
/**
* Options provided when sending a message as an inline reply.
* @typedef {BaseMessageOptions} ReplyMessageOptions
* @typedef {BaseMessageCreateOptions} MessageReplyOptions
* @property {StickerResolvable[]} [stickers=[]] The stickers to send in the message
* @property {boolean} [failIfNotExists=this.client.options.failIfNotExists] Whether to error if the referenced
* message does not exist (creates a standard message in this case when false)
* @property {StickerResolvable[]} [stickers=[]] Stickers to send in the message
@@ -778,7 +763,7 @@ class Message extends Base {
/**
* Send an inline reply to this message.
* @param {string|MessagePayload|ReplyMessageOptions} options The options to provide
* @param {string|MessagePayload|MessageReplyOptions} options The options to provide
* @returns {Promise<Message>}
* @example
* // Reply to a message

View File

@@ -17,7 +17,7 @@ const getBaseInteraction = lazy(() => require('./BaseInteraction'));
class MessagePayload {
/**
* @param {MessageTarget} target The target for this message to be sent to
* @param {MessageOptions|WebhookMessageOptions} options Options passed in from send
* @param {MessagePayloadOption} options The payload of this message
*/
constructor(target, options) {
/**
@@ -27,8 +27,8 @@ class MessagePayload {
this.target = target;
/**
* Options passed in from send
* @type {MessageOptions|WebhookMessageOptions}
* The payload of this message.
* @type {MessagePayloadOption}
*/
this.options = options;
@@ -261,8 +261,8 @@ class MessagePayload {
/**
* Creates a {@link MessagePayload} from user-level arguments.
* @param {MessageTarget} target Target to send to
* @param {string|MessageOptions|WebhookMessageOptions} options Options or content to use
* @param {MessageOptions|WebhookMessageOptions} [extra={}] Extra options to add onto specified options
* @param {string|MessagePayloadOption} options Options or content to use
* @param {MessagePayloadOption} [extra={}] Extra options to add onto specified options
* @returns {MessagePayload}
*/
static create(target, options, extra = {}) {
@@ -281,6 +281,12 @@ module.exports = MessagePayload;
* Message|MessageManager} MessageTarget
*/
/**
* A possible payload option.
* @typedef {MessageCreateOptions|MessageEditOptions|WebhookCreateMessageOptions|WebhookEditMessageOptions|
* InteractionReplyOptions|InteractionUpdateOptions} MessagePayloadOption
*/
/**
* @external APIMessage
* @see {@link https://discord.com/developers/docs/resources/channel#message-object}

View File

@@ -122,33 +122,27 @@ class Webhook {
/**
* Options that can be passed into send.
* @typedef {BaseMessageOptions} WebhookMessageOptions
* @typedef {BaseMessageOptions} WebhookCreateMessageOptions
* @property {boolean} [tts=false] Whether the message should be spoken aloud
* @property {MessageFlags} [flags] Which flags to set for the message.
* <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be set.</info>
* @property {string} [username=this.name] Username override for the message
* @property {string} [avatarURL] Avatar URL override for the message
* @property {Snowflake} [threadId] The id of the thread in the channel to send to.
* <info>For interaction webhooks, this property is ignored</info>
* @property {MessageFlags} [flags] Which flags to set for the message.
* <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be set.</info>
*/
/**
* Options that can be passed into editMessage.
* @typedef {Object} WebhookEditMessageOptions
* @property {Embed[]|APIEmbed[]} [embeds] See {@link WebhookMessageOptions#embeds}
* @property {string} [content] See {@link BaseMessageOptions#content}
* @property {JSONEncodable<AttachmentPayload>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
* See {@link BaseMessageOptions#files}
* @property {MessageMentionOptions} [allowedMentions] See {@link BaseMessageOptions#allowedMentions}
* @typedef {BaseMessageOptions} WebhookEditMessageOptions
* @property {Attachment[]} [attachments] Attachments to send with the message
* @property {ActionRow[]|ActionRowOptions[]} [components]
* Action rows containing interactive components for the message (buttons, select menus)
* @property {Snowflake} [threadId] The id of the thread this message belongs to
* <info>For interaction webhooks, this property is ignored</info>
*/
/**
* Sends a message with this webhook.
* @param {string|MessagePayload|WebhookMessageOptions} options The options to provide
* @param {string|MessagePayload|WebhookCreateMessageOptions} options The options to provide
* @returns {Promise<Message>}
* @example
* // Send a basic message

View File

@@ -33,12 +33,13 @@ class InteractionResponses {
*/
/**
* Options for a reply to an {@link BaseInteraction}.
* Options for a reply to a {@link BaseInteraction}.
* @typedef {BaseMessageOptions} InteractionReplyOptions
* @property {boolean} [tts=false] Whether the message should be spoken aloud
* @property {boolean} [ephemeral] Whether the reply should be ephemeral
* @property {boolean} [fetchReply] Whether to fetch the reply
* @property {MessageFlags} [flags] Which flags to set for the message.
* Only `MessageFlags.SuppressEmbeds` and `MessageFlags.Ephemeral` can be set.
* <info>Only `MessageFlags.SuppressEmbeds` and `MessageFlags.Ephemeral` can be set.</info>
*/
/**

View File

@@ -52,27 +52,35 @@ class TextBasedChannel {
}
/**
* Base options provided when sending.
* The base message options for messages.
* @typedef {Object} BaseMessageOptions
* @property {boolean} [tts=false] Whether or not the message should be spoken aloud
* @property {string} [nonce=''] The nonce for the message
* @property {string} [content=''] The content for the message
* @property {string|null} [content=''] The content for the message. This can only be `null` when editing a message.
* @property {Embed[]|APIEmbed[]} [embeds] The embeds for the message
* (see [here](https://discord.com/developers/docs/resources/channel#embed-object) for more details)
* @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
* (see [here](https://discord.com/developers/docs/resources/channel#allowed-mentions-object) for more details)
* @property {FileOptions[]|BufferResolvable[]|Attachment[]} [files] Files to send with the message
* @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
* The files to send with the message.
* @property {ActionRow[]|ActionRowOptions[]} [components]
* Action rows containing interactive components for the message (buttons, select menus)
* @property {Array<JSONEncodable<AttachmentPayload>>} [attachments] Attachments to send in the message
*/
/**
* Options provided when sending or editing a message.
* @typedef {BaseMessageOptions} MessageOptions
* Options for sending a message with a reply.
* @typedef {Object} ReplyOptions
* @property {MessageResolvable} messageReference The message to reply to (must be in the same channel and not system)
* @property {boolean} [failIfNotExists=this.client.options.failIfNotExists] Whether to error if the referenced
* message does not exist (creates a standard message in this case when false)
*/
/**
* The options for sending a message.
* @typedef {BaseMessageOptions} MessageCreateOptions
* @property {boolean} [tts=false] Whether the message should be spoken aloud
* @property {string} [nonce=''] The nonce for the message
* @property {ReplyOptions} [reply] The options for replying to a message
* @property {StickerResolvable[]} [stickers=[]] Stickers to send in the message
* @property {MessageFlags} [flags] Which flags to set for the message. Only `MessageFlags.SuppressEmbeds` can be set.
* @property {StickerResolvable[]} [stickers=[]] The stickers to send in the message
* @property {MessageFlags} [flags] Which flags to set for the message.
* <info>Only `MessageFlags.SuppressEmbeds` can be set.</info>
*/
/**
@@ -99,17 +107,9 @@ class TextBasedChannel {
* @property {string} description The description of the file
*/
/**
* Options for sending a message with a reply.
* @typedef {Object} ReplyOptions
* @property {MessageResolvable} messageReference The message to reply to (must be in the same channel and not system)
* @property {boolean} [failIfNotExists=this.client.options.failIfNotExists] Whether to error if the referenced
* message does not exist (creates a standard message in this case when false)
*/
/**
* Sends a message to this channel.
* @param {string|MessagePayload|MessageOptions} options The options to provide
* @param {string|MessagePayload|MessageCreateOptions} options The options to provide
* @returns {Promise<Message>}
* @example
* // Send a basic message

View File

@@ -25,12 +25,12 @@ const { toSnakeCase } = require('./Transformers');
* You can use your own function, or the {@link Options} class to customize the Collection used for the cache.
* <warn>Overriding the cache used in `GuildManager`, `ChannelManager`, `GuildChannelManager`, `RoleManager`,
* and `PermissionOverwriteManager` is unsupported and **will** break functionality</warn>
* @property {MessageMentionOptions} [allowedMentions] Default value for {@link MessageOptions#allowedMentions}
* @property {MessageMentionOptions} [allowedMentions] The default value for {@link BaseMessageOptions#allowedMentions}
* @property {Partials[]} [partials] Structures allowed to be partial. This means events can be emitted even when
* they're missing all the data for a particular structure. See the "Partial Structures" topic on the
* [guide](https://discordjs.guide/popular-topics/partials.html) for some
* important usage information, as partials require you to put checks in place when handling data.
* @property {boolean} [failIfNotExists=true] Default value for {@link ReplyMessageOptions#failIfNotExists}
* @property {boolean} [failIfNotExists=true] The default value for {@link MessageReplyOptions#failIfNotExists}
* @property {PresenceData} [presence={}] Presence data to use upon login
* @property {IntentsResolvable} intents Intents to enable for this connection
* @property {number} [waitGuildTimeout=15_000] Time in milliseconds that clients with the

View File

@@ -1718,7 +1718,7 @@ export class Message<InGuild extends boolean = boolean> extends Base {
public pin(reason?: string): Promise<Message<InGuild>>;
public react(emoji: EmojiIdentifierResolvable): Promise<MessageReaction>;
public removeAttachments(): Promise<Message<InGuild>>;
public reply(options: string | MessagePayload | ReplyMessageOptions): Promise<Message<InGuild>>;
public reply(options: string | MessagePayload | MessageReplyOptions): Promise<Message<InGuild>>;
public resolveComponent(customId: string): MessageActionRowComponent | null;
public startThread(options: StartThreadOptions): Promise<AnyThreadChannel>;
public suppressEmbeds(suppress?: boolean): Promise<Message<InGuild>>;
@@ -1875,8 +1875,16 @@ export class MessageMentions {
public static UsersPattern: typeof FormattingPatterns.User;
}
export type MessagePayloadOption =
| MessageCreateOptions
| MessageEditOptions
| WebhookCreateMessageOptions
| WebhookEditMessageOptions
| InteractionReplyOptions
| InteractionUpdateOptions;
export class MessagePayload {
public constructor(target: MessageTarget, options: MessageOptions | WebhookMessageOptions);
public constructor(target: MessageTarget, options: MessagePayloadOption);
public body: RawMessagePayloadData | null;
public get isUser(): boolean;
public get isWebhook(): boolean;
@@ -1884,13 +1892,13 @@ export class MessagePayload {
public get isMessageManager(): boolean;
public get isInteraction(): boolean;
public files: RawFile[] | null;
public options: MessageOptions | WebhookMessageOptions;
public options: MessagePayloadOption;
public target: MessageTarget;
public static create(
target: MessageTarget,
options: string | MessageOptions | WebhookMessageOptions,
extra?: MessageOptions | WebhookMessageOptions,
options: string | MessagePayloadOption,
extra?: MessagePayloadOption,
): MessagePayload;
public static resolveFile(
fileLike: BufferResolvable | Stream | AttachmentPayload | JSONEncodable<AttachmentPayload>,
@@ -2831,7 +2839,7 @@ export class Webhook extends WebhookMixin() {
options: string | MessagePayload | WebhookEditMessageOptions,
): Promise<Message>;
public fetchMessage(message: Snowflake, options?: WebhookFetchMessageOptions): Promise<Message>;
public send(options: string | MessagePayload | Omit<WebhookMessageOptions, 'flags'>): Promise<Message>;
public send(options: string | MessagePayload | WebhookCreateMessageOptions): Promise<Message>;
}
export class WebhookClient extends WebhookMixin(BaseClient) {
@@ -2844,7 +2852,7 @@ export class WebhookClient extends WebhookMixin(BaseClient) {
options: string | MessagePayload | WebhookEditMessageOptions,
): Promise<APIMessage>;
public fetchMessage(message: Snowflake, options?: WebhookFetchMessageOptions): Promise<APIMessage>;
public send(options: string | MessagePayload | WebhookMessageOptions): Promise<APIMessage>;
public send(options: string | MessagePayload | WebhookCreateMessageOptions): Promise<APIMessage>;
}
export class WebSocketManager extends EventEmitter {
@@ -3627,7 +3635,7 @@ export class UserManager extends CachedManager<Snowflake, User, UserResolvable>
public deleteDM(user: UserResolvable): Promise<DMChannel>;
public fetch(user: UserResolvable, options?: BaseFetchOptions): Promise<User>;
public fetchFlags(user: UserResolvable, options?: BaseFetchOptions): Promise<UserFlagsBitField>;
public send(user: UserResolvable, options: string | MessagePayload | MessageOptions): Promise<Message>;
public send(user: UserResolvable, options: string | MessagePayload | MessageCreateOptions): Promise<Message>;
}
export class VoiceStateManager extends CachedManager<Snowflake, VoiceState, typeof VoiceState> {
@@ -3659,7 +3667,7 @@ export function TextBasedChannelMixin<
): Constructable<T & Omit<TextBasedChannelFields<InGuild>, I>>;
export interface PartialTextBasedChannelFields<InGuild extends boolean = boolean> {
send(options: string | MessagePayload | MessageOptions): Promise<Message<InGuild>>;
send(options: string | MessagePayload | MessageCreateOptions): Promise<Message<InGuild>>;
}
export interface TextBasedChannelFields<InGuild extends boolean = boolean>
@@ -3700,7 +3708,9 @@ export interface PartialWebhookFields {
options: string | MessagePayload | WebhookEditMessageOptions,
): Promise<APIMessage | Message>;
fetchMessage(message: Snowflake | '@original', options?: WebhookFetchMessageOptions): Promise<APIMessage | Message>;
send(options: string | MessagePayload | Omit<WebhookMessageOptions, 'flags'>): Promise<APIMessage | Message>;
send(
options: string | MessagePayload | InteractionReplyOptions | WebhookCreateMessageOptions,
): Promise<APIMessage | Message>;
}
export interface WebhookFields extends PartialWebhookFields {
@@ -5023,10 +5033,14 @@ export interface InteractionDeferReplyOptions {
export type InteractionDeferUpdateOptions = Omit<InteractionDeferReplyOptions, 'ephemeral'>;
export interface InteractionReplyOptions extends Omit<WebhookMessageOptions, 'username' | 'avatarURL' | 'flags'> {
export interface InteractionReplyOptions extends BaseMessageOptions {
tts?: boolean;
ephemeral?: boolean;
fetchReply?: boolean;
flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds' | 'Ephemeral'>, number>;
flags?: BitFieldResolvable<
Extract<MessageFlagsString, 'Ephemeral' | 'SuppressEmbeds'>,
MessageFlags.Ephemeral | MessageFlags.SuppressEmbeds
>;
}
export interface InteractionUpdateOptions extends MessageEditOptions {
@@ -5121,28 +5135,6 @@ export type MessageChannelComponentCollectorOptions<T extends CollectedMessageIn
'channel' | 'guild' | 'interactionType'
>;
export interface MessageEditOptions {
attachments?: JSONEncodable<AttachmentPayload>[];
content?: string | null;
embeds?: (JSONEncodable<APIEmbed> | APIEmbed)[] | null;
files?: (
| BufferResolvable
| Stream
| JSONEncodable<APIAttachment>
| Attachment
| AttachmentBuilder
| AttachmentPayload
)[];
flags?: BitFieldResolvable<MessageFlagsString, number>;
allowedMentions?: MessageMentionOptions;
components?: (
| JSONEncodable<APIActionRowComponent<APIMessageActionRowComponent>>
| ActionRow<MessageActionRowComponent>
| ActionRowData<MessageActionRowComponentData | MessageActionRowComponentBuilder>
| APIActionRowComponent<APIMessageActionRowComponent>
)[];
}
export interface MessageEvent {
data: WebSocket.Data;
type: string;
@@ -5172,16 +5164,9 @@ export interface MessageMentionOptions {
export type MessageMentionTypes = 'roles' | 'users' | 'everyone';
export interface MessageOptions {
tts?: boolean;
nonce?: string | number;
content?: string | null;
export interface BaseMessageOptions {
content?: string;
embeds?: (JSONEncodable<APIEmbed> | APIEmbed)[];
components?: (
| JSONEncodable<APIActionRowComponent<APIMessageActionRowComponent>>
| ActionRowData<MessageActionRowComponentData | MessageActionRowComponentBuilder>
| APIActionRowComponent<APIMessageActionRowComponent>
)[];
allowedMentions?: MessageMentionOptions;
files?: (
| BufferResolvable
@@ -5191,10 +5176,25 @@ export interface MessageOptions {
| AttachmentBuilder
| AttachmentPayload
)[];
components?: (
| JSONEncodable<APIActionRowComponent<APIMessageActionRowComponent>>
| ActionRowData<MessageActionRowComponentData | MessageActionRowComponentBuilder>
| APIActionRowComponent<APIMessageActionRowComponent>
)[];
}
export interface MessageCreateOptions extends BaseMessageOptions {
tts?: boolean;
nonce?: string | number;
reply?: ReplyOptions;
stickers?: StickerResolvable[];
flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds'>, MessageFlags.SuppressEmbeds>;
}
export interface MessageEditOptions extends Omit<BaseMessageOptions, 'content'> {
content?: string | null;
attachments?: JSONEncodable<AttachmentPayload>[];
flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds'>, number>;
flags?: BitFieldResolvable<Extract<MessageFlagsString, 'SuppressEmbeds'>, MessageFlags.SuppressEmbeds>;
}
export type MessageReactionResolvable =
@@ -5387,7 +5387,7 @@ export interface ReplyOptions {
failIfNotExists?: boolean;
}
export interface ReplyMessageOptions extends Omit<MessageOptions, 'reply'> {
export interface MessageReplyOptions extends Omit<MessageCreateOptions, 'reply'> {
failIfNotExists?: boolean;
}
@@ -5608,16 +5608,15 @@ export interface WebhookEditData {
reason?: string;
}
export type WebhookEditMessageOptions = Pick<
WebhookMessageOptions,
'content' | 'embeds' | 'files' | 'allowedMentions' | 'components' | 'attachments' | 'threadId'
>;
export interface WebhookEditMessageOptions extends Omit<MessageEditOptions, 'flags'> {
threadId?: Snowflake;
}
export interface WebhookFetchMessageOptions {
threadId?: Snowflake;
}
export interface WebhookMessageOptions extends Omit<MessageOptions, 'reply' | 'stickers'> {
export interface WebhookCreateMessageOptions extends Omit<MessageCreateOptions, 'nonce' | 'reply' | 'stickers'> {
username?: string;
avatarURL?: string;
threadId?: Snowflake;