Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-13 10:03:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(builders): Add some basic documentation (#9359)

Browse Source
This commit is contained in:
Jiralite
2023-04-10 21:09:51 +01:00
committed by GitHub
parent c0f2dd7131
commit 8073561824
36 changed files with 690 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
packages/builders/src/components/selectMenu/BaseSelectMenu.ts
View File

@@ -2,13 +2,18 @@ import type { APISelectMenuComponent } from 'discord-api-types/v10';
import { customIdValidator, disabledValidator, minMaxValidator, placeholderValidator } from '../Assertions.js';
import { ComponentBuilder } from '../Component.js';
/**
* The base select menu builder that contains common symbols for select menu builders.
*
* @typeParam SelectMenuType - The type of select menu this would be instantiated for.
*/
export class BaseSelectMenuBuilder<
SelectMenuType extends APISelectMenuComponent,
> extends ComponentBuilder<SelectMenuType> {
/**
* Sets the placeholder for this select menu
* Sets the placeholder for this select menu.
*
* @param placeholder - The placeholder to use for this select menu
* @param placeholder - The placeholder to use
*/
public setPlaceholder(placeholder: string) {
this.data.placeholder = placeholderValidator.parse(placeholder);
@@ -16,7 +21,7 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets the minimum values that must be selected in the select menu
* Sets the minimum values that must be selected in the select menu.
*
* @param minValues - The minimum values that must be selected
*/
@@ -26,7 +31,7 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets the maximum values that must be selected in the select menu
* Sets the maximum values that must be selected in the select menu.
*
* @param maxValues - The maximum values that must be selected
*/
@@ -36,9 +41,9 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets the custom id for this select menu
* Sets the custom id for this select menu.
*
* @param customId - The custom id to use for this select menu
* @param customId - The custom id to use
*/
public setCustomId(customId: string) {
this.data.custom_id = customIdValidator.parse(customId);
@@ -46,7 +51,7 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets whether this select menu is disabled
* Sets whether this select menu is disabled.
*
* @param disabled - Whether this select menu is disabled
*/
@@ -55,6 +60,9 @@ export class BaseSelectMenuBuilder<
return this;
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
*/
public toJSON(): SelectMenuType {
customIdValidator.parse(this.data.custom_id);
return {

45
packages/builders/src/components/selectMenu/ChannelSelectMenu.ts
View File

@@ -4,13 +4,16 @@ import { normalizeArray, type RestOrArray } from '../../util/normalizeArray.js';
import { channelTypesValidator, customIdValidator } from '../Assertions.js';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for channel select menus.
*/
export class ChannelSelectMenuBuilder extends BaseSelectMenuBuilder<APIChannelSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new ChannelSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -19,39 +22,45 @@ export class ChannelSelectMenuBuilder extends BaseSelectMenuBuilder<APIChannelSe
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new ChannelSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .addChannelTypes(ChannelType.GuildText, ChannelType.GuildAnnouncement)
* .setMinValues(2)
* .setMinValues(2);
* ```
*/
public constructor(data?: Partial<APIChannelSelectComponent>) {
super({ ...data, type: ComponentType.ChannelSelect });
}
/**
* Adds channel types to this select menu.
*
* @param types - The channel types to use
*/
public addChannelTypes(...types: RestOrArray<ChannelType>) {
// eslint-disable-next-line no-param-reassign
types = normalizeArray(types);
const normalizedTypes = normalizeArray(types);
this.data.channel_types ??= [];
this.data.channel_types.push(...channelTypesValidator.parse(types));
return this;
}
public setChannelTypes(...types: RestOrArray<ChannelType>) {
// eslint-disable-next-line no-param-reassign
types = normalizeArray(types);
this.data.channel_types ??= [];
this.data.channel_types.splice(0, this.data.channel_types.length, ...channelTypesValidator.parse(types));
this.data.channel_types.push(...channelTypesValidator.parse(normalizedTypes));
return this;
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
* Sets channel types for this select menu.
*
* @param types - The channel types to use
*/
public setChannelTypes(...types: RestOrArray<ChannelType>) {
const normalizedTypes = normalizeArray(types);
this.data.channel_types ??= [];
this.data.channel_types.splice(0, this.data.channel_types.length, ...channelTypesValidator.parse(normalizedTypes));
return this;
}
/**
* {@inheritDoc BaseSelectMenuBuilder.toJSON}
*/
public override toJSON(): APIChannelSelectComponent {
customIdValidator.parse(this.data.custom_id);

11
packages/builders/src/components/selectMenu/MentionableSelectMenu.ts
View File

@@ -2,13 +2,16 @@ import type { APIMentionableSelectComponent } from 'discord-api-types/v10';
import { ComponentType } from 'discord-api-types/v10';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for mentionable select menus.
*/
export class MentionableSelectMenuBuilder extends BaseSelectMenuBuilder<APIMentionableSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new MentionableSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -17,12 +20,12 @@ export class MentionableSelectMenuBuilder extends BaseSelectMenuBuilder<APIMenti
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new MentionableSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .setMinValues(1)
* .setMinValues(1);
* ```
*/
public constructor(data?: Partial<APIMentionableSelectComponent>) {

11
packages/builders/src/components/selectMenu/RoleSelectMenu.ts
View File

@@ -2,13 +2,16 @@ import type { APIRoleSelectComponent } from 'discord-api-types/v10';
import { ComponentType } from 'discord-api-types/v10';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for role select menus.
*/
export class RoleSelectMenuBuilder extends BaseSelectMenuBuilder<APIRoleSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new RoleSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -17,12 +20,12 @@ export class RoleSelectMenuBuilder extends BaseSelectMenuBuilder<APIRoleSelectCo
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new RoleSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .setMinValues(1)
* .setMinValues(1);
* ```
*/
public constructor(data?: Partial<APIRoleSelectComponent>) {

62
packages/builders/src/components/selectMenu/StringSelectMenu.ts
View File

@@ -6,20 +6,20 @@ import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
import { StringSelectMenuOptionBuilder } from './StringSelectMenuOption.js';
/**
* Represents a string select menu component
* A builder that creates API-compatible JSON data for string select menus.
*/
export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSelectComponent> {
/**
* The options within this select menu
* The options within this select menu.
*/
public readonly options: StringSelectMenuOptionBuilder[];
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new StringSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -33,7 +33,7 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new StringSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -52,55 +52,52 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
}
/**
* Adds options to this select menu
* Adds options to this select menu.
*
* @param options - The options to add to this select menu
* @returns
* @param options - The options to add
*/
public addOptions(...options: RestOrArray<APISelectMenuOption | StringSelectMenuOptionBuilder>) {
// eslint-disable-next-line no-param-reassign
options = normalizeArray(options);
optionsLengthValidator.parse(this.options.length + options.length);
const normalizedOptions = normalizeArray(options);
optionsLengthValidator.parse(this.options.length + normalizedOptions.length);
this.options.push(
...options.map((option) =>
option instanceof StringSelectMenuOptionBuilder
? option
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(option)),
...normalizedOptions.map((normalizedOption) =>
normalizedOption instanceof StringSelectMenuOptionBuilder
? normalizedOption
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(normalizedOption)),
),
);
return this;
}
/**
* Sets the options on this select menu
* Sets the options for this select menu.
*
* @param options - The options to set on this select menu
* @param options - The options to set
*/
public setOptions(...options: RestOrArray<APISelectMenuOption | StringSelectMenuOptionBuilder>) {
return this.spliceOptions(0, this.options.length, ...options);
}
/**
* Removes, replaces, or inserts options in the string select menu.
* Removes, replaces, or inserts options for this select menu.
*
* @remarks
* This method behaves similarly
* to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice | Array.prototype.splice}.
*
* It's useful for modifying and adjusting order of the already-existing options of a string select menu.
* to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice | Array.prototype.splice()}.
* It's useful for modifying and adjusting the order of existing options.
* @example
* Remove the first option
* Remove the first option:
* ```ts
* selectMenu.spliceOptions(0, 1);
* ```
* @example
* Remove the first n option
* Remove the first n option:
* ```ts
* const n = 4
* const n = 4;
* selectMenu.spliceOptions(0, n);
* ```
* @example
* Remove the last option
* Remove the last option:
* ```ts
* selectMenu.spliceOptions(-1, 1);
* ```
@@ -113,30 +110,27 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
deleteCount: number,
...options: RestOrArray<APISelectMenuOption | StringSelectMenuOptionBuilder>
) {
// eslint-disable-next-line no-param-reassign
options = normalizeArray(options);
const normalizedOptions = normalizeArray(options);
const clone = [...this.options];
clone.splice(
index,
deleteCount,
...options.map((option) =>
option instanceof StringSelectMenuOptionBuilder
? option
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(option)),
...normalizedOptions.map((normalizedOption) =>
normalizedOption instanceof StringSelectMenuOptionBuilder
? normalizedOption
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(normalizedOption)),
),
);
optionsLengthValidator.parse(clone.length);
this.options.splice(0, this.options.length, ...clone);
return this;
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
* {@inheritDoc BaseSelectMenuBuilder.toJSON}
*/
public override toJSON(): APIStringSelectComponent {
validateRequiredSelectMenuParameters(this.options, this.data.custom_id);

30
packages/builders/src/components/selectMenu/StringSelectMenuOption.ts
View File

@@ -8,15 +8,15 @@ import {
} from '../Assertions.js';
/**
* Represents an option within a string select menu component
* A builder that creates API-compatible JSON data for string select menu options.
*/
export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMenuOption> {
/**
* Creates a new string select menu option from API data
* Creates a new string select menu option from API data.
*
* @param data - The API data to create this string select menu option with
* @example
* Creating a string select menu option from an API data object
* Creating a string select menu option from an API data object:
* ```ts
* const selectMenuOption = new SelectMenuOptionBuilder({
* label: 'catchy label',
@@ -24,21 +24,21 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
* });
* ```
* @example
* Creating a string select menu option using setters and API data
* Creating a string select menu option using setters and API data:
* ```ts
* const selectMenuOption = new SelectMenuOptionBuilder({
* default: true,
* value: '1',
* })
* .setLabel('woah')
* .setLabel('woah');
* ```
*/
public constructor(public data: Partial<APISelectMenuOption> = {}) {}
/**
* Sets the label of this option
* Sets the label for this option.
*
* @param label - The label to show on this option
* @param label - The label to use
*/
public setLabel(label: string) {
this.data.label = labelValueDescriptionValidator.parse(label);
@@ -46,9 +46,9 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets the value of this option
* Sets the value for this option.
*
* @param value - The value of this option
* @param value - The value to use
*/
public setValue(value: string) {
this.data.value = labelValueDescriptionValidator.parse(value);
@@ -56,9 +56,9 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets the description of this option
* Sets the description for this option.
*
* @param description - The description of this option
* @param description - The description to use
*/
public setDescription(description: string) {
this.data.description = labelValueDescriptionValidator.parse(description);
@@ -66,7 +66,7 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets whether this option is selected by default
* Sets whether this option is selected by default.
*
* @param isDefault - Whether this option is selected by default
*/
@@ -76,9 +76,9 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets the emoji to display on this option
* Sets the emoji to display for this option.
*
* @param emoji - The emoji to display on this option
* @param emoji - The emoji to use
*/
public setEmoji(emoji: APIMessageComponentEmoji) {
this.data.emoji = emojiValidator.parse(emoji);
@@ -86,7 +86,7 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
* {@inheritDoc BaseSelectMenuBuilder.toJSON}
*/
public toJSON(): APISelectMenuOption {
validateRequiredSelectMenuOptionParameters(this.data.label, this.data.value);

11
packages/builders/src/components/selectMenu/UserSelectMenu.ts
View File

@@ -2,13 +2,16 @@ import type { APIUserSelectComponent } from 'discord-api-types/v10';
import { ComponentType } from 'discord-api-types/v10';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for user select menus.
*/
export class UserSelectMenuBuilder extends BaseSelectMenuBuilder<APIUserSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new UserSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -17,12 +20,12 @@ export class UserSelectMenuBuilder extends BaseSelectMenuBuilder<APIUserSelectCo
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new UserSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .setMinValues(1)
* .setMinValues(1);
* ```
*/
public constructor(data?: Partial<APIUserSelectComponent>) {