document code with jsdoc comments

This commit is contained in:
Baipyrus 2024-02-11 02:04:12 +01:00
parent ffa4d43d8f
commit 80d4693c3d
19 changed files with 222 additions and 32 deletions

View File

@ -1,4 +1,9 @@
import { ChannelType, PermissionFlagsBits, SlashCommandBuilder } from 'discord.js'; import {
ChannelType,
PermissionFlagsBits,
SlashCommandBuilder,
ChatInputCommandInteraction
} from 'discord.js';
import { VoiceChannel } from '../../../database.js'; import { VoiceChannel } from '../../../database.js';
export const data = new SlashCommandBuilder() export const data = new SlashCommandBuilder()
@ -41,9 +46,11 @@ export const data = new SlashCommandBuilder()
.setDescription('The voice channel to be unregistered.') .setDescription('The voice channel to be unregistered.')
) )
); );
/** @param {ChatInputCommandInteraction} interaction */
export async function execute(interaction) { export async function execute(interaction) {
const { guild, options } = interaction; const { guild, options } = interaction;
/** @type {string} */
let step; let step;
try { try {
switch (options.getSubcommand()) { switch (options.getSubcommand()) {

View File

@ -1,9 +1,13 @@
import { PermissionFlagsBits, TextInputBuilder, TextInputStyle } from 'discord.js';
import { import {
ModalBuilder, ModalBuilder,
TextInputStyle,
ActionRowBuilder, ActionRowBuilder,
TextInputBuilder,
PermissionFlagsBits,
ModalSubmitInteraction,
ApplicationCommandType, ApplicationCommandType,
ContextMenuCommandBuilder ContextMenuCommandBuilder,
ContextMenuCommandInteraction
} from 'discord.js'; } from 'discord.js';
import { addSelfRoles } from '../../../../shared.js'; import { addSelfRoles } from '../../../../shared.js';
@ -12,6 +16,7 @@ export const data = new ContextMenuCommandBuilder()
.setName('Add role emoji pair') .setName('Add role emoji pair')
.setType(ApplicationCommandType.Message) .setType(ApplicationCommandType.Message)
.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles); .setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles);
/** @param {ModalSubmitInteraction} interaction */
export async function modalSubmit(interaction) { export async function modalSubmit(interaction) {
const { fields, guild } = interaction; const { fields, guild } = interaction;
// Get text inputs from modal // Get text inputs from modal
@ -32,6 +37,7 @@ export async function modalSubmit(interaction) {
await addSelfRoles(interaction, message, role, emoji); await addSelfRoles(interaction, message, role, emoji);
} }
/** @param {ContextMenuCommandInteraction} interaction */
export async function execute(interaction) { export async function execute(interaction) {
const modal = new ModalBuilder() const modal = new ModalBuilder()
.setCustomId('Add role emoji pair-pair') .setCustomId('Add role emoji pair-pair')

View File

@ -1,11 +1,17 @@
import {
ApplicationCommandType,
ContextMenuCommandBuilder,
PermissionFlagsBits,
ContextMenuCommandInteraction
} from 'discord.js';
import { Message } from '../../../../database.js'; import { Message } from '../../../../database.js';
import { ApplicationCommandType, ContextMenuCommandBuilder, PermissionFlagsBits } from 'discord.js';
export const data = new ContextMenuCommandBuilder() export const data = new ContextMenuCommandBuilder()
.setDMPermission(false) .setDMPermission(false)
.setName('Register self roles') .setName('Register self roles')
.setType(ApplicationCommandType.Message) .setType(ApplicationCommandType.Message)
.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles); .setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles);
/** @param {ContextMenuCommandInteraction} interaction */
export async function execute(interaction) { export async function execute(interaction) {
const id = interaction.targetMessage.id; const id = interaction.targetMessage.id;

View File

@ -1,11 +1,17 @@
import {
ApplicationCommandType,
ContextMenuCommandBuilder,
PermissionFlagsBits,
ContextMenuCommandInteraction
} from 'discord.js';
import { removeSelfRoles } from '../../../../shared.js'; import { removeSelfRoles } from '../../../../shared.js';
import { ApplicationCommandType, ContextMenuCommandBuilder, PermissionFlagsBits } from 'discord.js';
export const data = new ContextMenuCommandBuilder() export const data = new ContextMenuCommandBuilder()
.setDMPermission(false) .setDMPermission(false)
.setName('Remove self roles') .setName('Remove self roles')
.setType(ApplicationCommandType.Message) .setType(ApplicationCommandType.Message)
.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles); .setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles);
/** @param {ContextMenuCommandInteraction} interaction */
export async function execute(interaction) { export async function execute(interaction) {
const id = interaction.targetMessage.id; const id = interaction.targetMessage.id;
await removeSelfRoles(interaction, id); await removeSelfRoles(interaction, id);

View File

@ -1,7 +1,12 @@
import { addSelfRoles } from '../../../shared.js'; import { PermissionFlagsBits, SlashCommandBuilder, ChatInputCommandInteraction } from 'discord.js';
import { PermissionFlagsBits, SlashCommandBuilder } from 'discord.js'; import { addSelfRoles, removeSelfRoles } from '../../../shared.js';
import { Message } from '../../../database.js'; import { Message } from '../../../database.js';
/**
* Sends a `Message` in the current channel and registers for self roles.
* @param {ChatInputCommandInteraction} interaction
* @returns {string}
*/
const createSelfRoles = async (interaction) => { const createSelfRoles = async (interaction) => {
const { options, channel } = interaction; const { options, channel } = interaction;
@ -16,6 +21,17 @@ const createSelfRoles = async (interaction) => {
return id; return id;
}; };
/**
* @typedef {Object} SelfRoleResponse
* @property {boolean} success Whether or not the operation was successful.
* @property {string|null} msgID A Discord message ID, if successful.
*/
/**
* Registers a `Message` for self roles.
* @param {ChatInputCommandInteraction} interaction
* @returns {Promise<SelfRoleResponse>}
*/
const registerSelfRoles = async (interaction) => { const registerSelfRoles = async (interaction) => {
const { options, channel } = interaction; const { options, channel } = interaction;
const id = options.getString('id'); const id = options.getString('id');
@ -50,7 +66,12 @@ const registerSelfRoles = async (interaction) => {
return response; return response;
}; };
const removeSelfRoles = async (interaction, msgID) => { /**
* Main logic of the 'Self Roles remove' slash command to remove the functionality from a `Message`.
* @param {ChatInputCommandInteraction} interaction
* @param {string} msgID A Discord message ID.
*/
const removeReactionRoles = async (interaction, msgID) => {
const { channel } = interaction; const { channel } = interaction;
try { try {
@ -66,6 +87,7 @@ const removeSelfRoles = async (interaction, msgID) => {
return; return;
} }
// Call shared method for further logic
await removeSelfRoles(interaction, msgID); await removeSelfRoles(interaction, msgID);
}; };
@ -124,11 +146,13 @@ export const data = new SlashCommandBuilder()
.setDescription('The ID to reference the message to be removed.') .setDescription('The ID to reference the message to be removed.')
) )
); );
/** @param {ChatInputCommandInteraction} interaction */
export async function execute(interaction) { export async function execute(interaction) {
const { options } = interaction; const { options } = interaction;
let createNew = false, /** @type {string=} */
id; let id;
let createNew = false;
switch (options.getSubcommand()) { switch (options.getSubcommand()) {
case 'create': case 'create':
id = await createSelfRoles(interaction); id = await createSelfRoles(interaction);
@ -153,7 +177,7 @@ export async function execute(interaction) {
} }
case 'remove': { case 'remove': {
const msgID = options.getString('id'); const msgID = options.getString('id');
await removeSelfRoles(interaction, msgID); await removeReactionRoles(interaction, msgID);
break; break;
} }
} }

View File

@ -6,6 +6,7 @@ import { config } from 'dotenv';
config(); config();
const { DB_NAME } = process.env; const { DB_NAME } = process.env;
/** The database instance used as an ORM in this project. */
const sequelize = new Sequelize({ const sequelize = new Sequelize({
storage: `${DB_NAME}.sqlite`, storage: `${DB_NAME}.sqlite`,
dialect: 'sqlite', dialect: 'sqlite',

View File

@ -3,13 +3,17 @@ import { REST, Routes } from 'discord.js';
import { join, dirname } from 'path'; import { join, dirname } from 'path';
import { fileURLToPath } from 'url'; import { fileURLToPath } from 'url';
import { config } from 'dotenv'; import { config } from 'dotenv';
import Module from 'module';
config(); config();
// Construct and prepare an instance of the REST module // Construct and prepare an instance of the REST module
const rest = new REST().setToken(process.env.TOKEN); const rest = new REST().setToken(process.env.TOKEN);
// and deploy your commands! /**
* Calls HTTP PUT to register commands in discord.
* @param {Array<Object>} commands
*/
const putCommands = async (commands) => { const putCommands = async (commands) => {
try { try {
console.info(`[INFO] Started refreshing ${commands.length} application (/) commands.`); console.info(`[INFO] Started refreshing ${commands.length} application (/) commands.`);
@ -32,7 +36,7 @@ getFiles(cmdPath)
// For each command file // For each command file
.then(async (files) => .then(async (files) =>
(await Promise.all(files.map(importAndCheck))) (await Promise.all(files.map(importAndCheck)))
.filter((module) => module !== 0) .filter(/** @param {(Module|0)} module */ (module) => module !== 0)
.map((module) => module.data.toJSON()) .map(/** @param {Module} module */ (module) => module.data.toJSON())
) )
.then(putCommands); .then(putCommands);

View File

@ -1,7 +1,8 @@
import { ChannelType, Events } from 'discord.js'; import { ChannelType, Events, GuildChannel } from 'discord.js';
import { VoiceChannel } from '../../database.js'; import { VoiceChannel } from '../../database.js';
export const name = Events.ChannelDelete; export const name = Events.ChannelDelete;
/** @param {GuildChannel} channel */
export async function execute(channel) { export async function execute(channel) {
if (channel.type !== ChannelType.GuildVoice) return; if (channel.type !== ChannelType.GuildVoice) return;

View File

@ -1,4 +1,12 @@
import { ChannelType, Events, PermissionFlagsBits } from 'discord.js'; import {
ChannelType,
Events,
PermissionFlagsBits,
GuildMember,
GuildChannelManager,
GuildChannel,
VoiceState
} from 'discord.js';
import { VoiceChannel } from '../../database.js'; import { VoiceChannel } from '../../database.js';
const vcPermissionOverwrites = [ const vcPermissionOverwrites = [
@ -17,6 +25,13 @@ const vcPermissionOverwrites = [
PermissionFlagsBits.Speak PermissionFlagsBits.Speak
]; ];
/**
* Function that either creates a new custom channel or gets an existing one registered in the database.
* @param {GuildMember} member The member that caused this event.
* @param {GuildChannelManager} guildChs All channels in this guild.
* @param {GuildChannel} channel The channel the member joined for this event to trigger.
* @returns {Promise<GuildChannel>} The channel, whether it's newly created or not.
*/
const getChannel = async (member, guildChs, channel) => { const getChannel = async (member, guildChs, channel) => {
// Check database for existing channel // Check database for existing channel
const ownCh = await VoiceChannel.findOne({ const ownCh = await VoiceChannel.findOne({
@ -52,6 +67,10 @@ const getChannel = async (member, guildChs, channel) => {
return privCh; return privCh;
}; };
/**
* Function to delete the voice channel, if and only if the user is currently leaving and it was a custom channel.
* @param {VoiceState} state The previous voice state the user was in.
*/
const leftVoiceChat = async (state) => { const leftVoiceChat = async (state) => {
const { channel } = state; const { channel } = state;
@ -77,8 +96,12 @@ const leftVoiceChat = async (state) => {
}; };
export const name = Events.VoiceStateUpdate; export const name = Events.VoiceStateUpdate;
/**
* @param {VoiceState} oldState
* @param {VoiceState} newState
*/
export async function execute(oldState, newState) { export async function execute(oldState, newState) {
const { channel } = newState const { channel } = newState;
await leftVoiceChat(oldState); await leftVoiceChat(oldState);
if (!channel) return; if (!channel) return;

View File

@ -1,5 +1,11 @@
import { Events } from 'discord.js'; import { Events } from 'discord.js';
import Module from 'module';
/**
* A more precise execution function specifically to call the main property of a module.
* @param {import('discord.js').Interaction} interaction
* @param {Module} command
*/
const executeCommand = async (interaction, command) => { const executeCommand = async (interaction, command) => {
// Try executing command // Try executing command
try { try {
@ -21,6 +27,14 @@ const executeCommand = async (interaction, command) => {
} }
}; };
/**
* A generic execution function to call command methods.
* @param {import('discord.js').Interaction} interaction
* @param {Module} command
* @param {string} name
* @param {string=} description
* @param {string=} cmdName
*/
const genericExecute = async (interaction, command, name, description, cmdName) => { const genericExecute = async (interaction, command, name, description, cmdName) => {
try { try {
console.info( console.info(
@ -35,7 +49,9 @@ const genericExecute = async (interaction, command, name, description, cmdName)
}; };
export const name = Events.InteractionCreate; export const name = Events.InteractionCreate;
/** @param {import('discord.js').Interaction} interaction */
export async function execute(interaction) { export async function execute(interaction) {
/** @type {Module} */
let command = interaction.client.commands.get(interaction.commandName); let command = interaction.client.commands.get(interaction.commandName);
// Execute slash- and context-menu-commands // Execute slash- and context-menu-commands

View File

@ -1,7 +1,8 @@
import { Events } from 'discord.js';
import { Message } from '../../database.js'; import { Message } from '../../database.js';
import { Events } from 'discord.js';
export const name = Events.MessageDelete; export const name = Events.MessageDelete;
/** @param {import('discord.js').Message} message */
export async function execute(message) { export async function execute(message) {
// Delete message entry once message is deleted itself // Delete message entry once message is deleted itself
const count = await Message.destroy({ const count = await Message.destroy({

View File

@ -1,10 +1,14 @@
import { config } from 'dotenv'; import { Events, MessageReaction, User } from 'discord.js';
import { Events } from 'discord.js';
import { Message, RoleEmojiPair } from '../../database.js'; import { Message, RoleEmojiPair } from '../../database.js';
import { config } from 'dotenv';
config(); config();
export const name = Events.MessageReactionAdd; export const name = Events.MessageReactionAdd;
/**
* @param {MessageReaction} reaction
* @param {User} user
*/
export async function execute(reaction, user) { export async function execute(reaction, user) {
if (user.id === process.env.CLIENT) return; if (user.id === process.env.CLIENT) return;

View File

@ -1,10 +1,14 @@
import { config } from 'dotenv'; import { Events, MessageReaction, User } from 'discord.js';
import { Events } from 'discord.js';
import { Message, RoleEmojiPair } from '../../database.js'; import { Message, RoleEmojiPair } from '../../database.js';
import { config } from 'dotenv';
config(); config();
export const name = Events.MessageReactionRemove; export const name = Events.MessageReactionRemove;
/**
* @param {MessageReaction} reaction
* @param {User} user
*/
export async function execute(reaction, user) { export async function execute(reaction, user) {
if (user.id === process.env.CLIENT) return; if (user.id === process.env.CLIENT) return;

View File

@ -1,7 +1,8 @@
import { Events } from 'discord.js'; import { Events, Client } from 'discord.js';
export const name = Events.ClientReady; export const name = Events.ClientReady;
export const once = true; export const once = true;
/** @param {Client} client */
export function execute(client) { export function execute(client) {
console.info(`[INFO] Ready! Logged in as ${client.user.tag}`); console.info(`[INFO] Ready! Logged in as ${client.user.tag}`);
} }

View File

@ -1,12 +1,17 @@
import { Client, Collection, GatewayIntentBits } from 'discord.js'; import { Client, Collection, GatewayIntentBits, Partials } from 'discord.js';
import { getFiles, importAndCheck } from './shared.js'; import { getFiles, importAndCheck } from './shared.js';
import { Partials } from 'discord.js';
import { join, dirname } from 'path'; import { join, dirname } from 'path';
import { fileURLToPath } from 'url'; import { fileURLToPath } from 'url';
import { config } from 'dotenv'; import { config } from 'dotenv';
import Module from 'module';
config(); config();
/**
* Main entry point, the bot logs on to discord.
* @param {Array<Module>} commands
* @param {Array<Module>} events
*/
const runClient = (commands, events) => { const runClient = (commands, events) => {
// Create a new client instance // Create a new client instance
const client = new Client({ const client = new Client({
@ -18,8 +23,15 @@ const runClient = (commands, events) => {
], ],
partials: [Partials.Message, Partials.Reaction] partials: [Partials.Message, Partials.Reaction]
}); });
/**
* The commands registered for this client.
* @type {Collection}
*/
client.commands = new Collection(); client.commands = new Collection();
commands.forEach((c) => client.commands.set(c.data.name, c)); commands.forEach((c) => client.commands.set(c.data.name, c));
// Register client events
events.forEach((e) => events.forEach((e) =>
e.once e.once
? client.once(e.name, (...args) => e.execute(...args)) ? client.once(e.name, (...args) => e.execute(...args))

View File

@ -1,5 +1,17 @@
import { DataTypes } from 'sequelize'; import { DataTypes, Sequelize } from 'sequelize';
/**
* @typedef {Object} Message
* @property {string} id A Discord message ID.
* @method hasMany Defines an One-To-Many relationship.
* @param {Object}
*/
/**
* The definition of the `Message` table in the database.
* @param {Sequelize} sequelize
* @returns {Message}
*/
export default function (sequelize) { export default function (sequelize) {
return sequelize.define('Messages', { return sequelize.define('Messages', {
id: { id: {

View File

@ -1,5 +1,18 @@
import { DataTypes, Deferrable } from 'sequelize'; import { DataTypes, Deferrable, Sequelize } from 'sequelize';
/**
* @typedef {Object} RoleEmojiPair
* @property {string} id A universally unique id, generated by sequelize.
* @property {string} message A Discord message ID as a foreign key reference.
* @property {string} role A Discord role ID.
* @property {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
*/
/**
* The definition of the `RoleEmojiPair` table in the database.
* @param {Sequelize} sequelize
* @returns {RoleEmojiPair}
*/
export default function (sequelize) { export default function (sequelize) {
return sequelize.define('RoleEmojiPairs', { return sequelize.define('RoleEmojiPairs', {
id: { id: {

View File

@ -1,5 +1,17 @@
import { DataTypes } from 'sequelize'; import { DataTypes, Sequelize } from 'sequelize';
/**
* @typedef {Object} VoiceChannel
* @property {string} id A Discord channel ID.
* @property {boolean} create Whether or not this channel is registered to create customs when joined.
* @property {(string|null)} owner The owner of this channel, if not registered for customs.
*/
/**
* The definition of the `VoiceChannel` table in the database.
* @param {Sequelize} sequelize
* @returns {VoiceChannel}
*/
export default function (sequelize) { export default function (sequelize) {
return sequelize.define('VoiceChannel', { return sequelize.define('VoiceChannel', {
id: { id: {

View File

@ -1,11 +1,18 @@
import { join } from 'path'; import { ChatInputCommandInteraction, ContextMenuCommandInteraction, Role } from 'discord.js';
import { Op } from 'sequelize';
import { config } from 'dotenv';
import { readdir } from 'fs/promises';
import { Message, RoleEmojiPair } from './database.js'; import { Message, RoleEmojiPair } from './database.js';
import { readdir } from 'fs/promises';
import { config } from 'dotenv';
import { Op } from 'sequelize';
import { join } from 'path';
import Module from 'module';
config(); config();
/**
* Main logic of the different 'Self Roles remove' commands to remove the functionality from a `Message`.
* @param {(ChatInputCommandInteraction|ContextMenuCommandInteraction)} interaction The interaction related to this command.
* @param {string} id A Discord message ID.
*/
export const removeSelfRoles = async (interaction, id) => { export const removeSelfRoles = async (interaction, id) => {
// Try deleting message from database // Try deleting message from database
const count = await Message.destroy({ const count = await Message.destroy({
@ -27,6 +34,12 @@ export const removeSelfRoles = async (interaction, id) => {
console.info(`[INFO] Removed self roles from message with ID '${id}'.`); console.info(`[INFO] Removed self roles from message with ID '${id}'.`);
}; };
/**
* Function to handle saving all the corresponding data for `Message` and `RoleEmojiPair` tables.
* @param {string} id A Discord message ID.
* @param {Role} role
* @param {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
*/
const saveMessageData = async (id, role, emoji) => { const saveMessageData = async (id, role, emoji) => {
// Try finding message // Try finding message
const msg = await Message.findOne({ where: { id } }); const msg = await Message.findOne({ where: { id } });
@ -56,6 +69,12 @@ const saveMessageData = async (id, role, emoji) => {
await RoleEmojiPair.create({ message: id, role: role.id, emoji }); await RoleEmojiPair.create({ message: id, role: role.id, emoji });
}; };
/**
* Function to handle editing messages in case the message that's getting a new `RoleEmojiPair`, is owned by the bot.
* @param {import('discord.js').Message} message
* @param {Role} role
* @param {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
*/
const editMessage = async (message, role, emoji) => { const editMessage = async (message, role, emoji) => {
if (message.author.id !== process.env.CLIENT) return; if (message.author.id !== process.env.CLIENT) return;
@ -72,6 +91,13 @@ const editMessage = async (message, role, emoji) => {
await message.edit(next); await message.edit(next);
}; };
/**
* Main logic of the different 'Self Roles add' commands to add a `RoleEmojiPair` to the database and the `Message`.
* @param {(ChatInputCommandInteraction|ContextMenuCommandInteraction)} interaction The interaction related to this command.
* @param {string} msgID A Discord message ID.
* @param {Role} role
* @param {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
*/
export const addSelfRoles = async (interaction, msgID, role, emoji) => { export const addSelfRoles = async (interaction, msgID, role, emoji) => {
const { channel } = interaction; const { channel } = interaction;
@ -109,9 +135,15 @@ export const addSelfRoles = async (interaction, msgID, role, emoji) => {
} }
}; };
// Lists of required and optional attributes of command modules
const required = ['data', 'execute']; const required = ['data', 'execute'];
const optional = ['autocomplete', 'modalSubmit']; const optional = ['autocomplete', 'modalSubmit'];
/**
* Recursively scans a directory for all files in it.
* @param {string} dir
* @returns {Array<string>} Array of paths to the files within.
*/
export const getFiles = async (dir) => { export const getFiles = async (dir) => {
const dirents = await readdir(dir, { withFileTypes: true }); const dirents = await readdir(dir, { withFileTypes: true });
const files = await Promise.all( const files = await Promise.all(
@ -123,6 +155,11 @@ export const getFiles = async (dir) => {
return Array.prototype.concat(...files); return Array.prototype.concat(...files);
}; };
/**
* Imports and checks a command from a path as a module.
* @param {string} filePath
* @returns {Promise<Module|0>}
*/
export const importAndCheck = async (filePath) => { export const importAndCheck = async (filePath) => {
if (!filePath.endsWith('.js') || filePath.endsWith('.example.js')) { if (!filePath.endsWith('.js') || filePath.endsWith('.example.js')) {
// Skip this file // Skip this file