From 53ea4063ac7c7e91f33eb76c35088f3d078f4f59 Mon Sep 17 00:00:00 2001
From: Tristan Guichaoua <33934311+tguichaoua@users.noreply.github.com>
Date: Sun, 17 Oct 2021 16:34:54 +0200
Subject: [PATCH] doc: update doc (#14)
* doc(Readme): update description
* update the 'how to use' section
* package: update description and keywords
* Readme: fix typo
---
README.md | 168 +++++++++++++++++++++++++++++++++++++++------------
package.json | 6 +-
2 files changed, 135 insertions(+), 39 deletions(-)
diff --git a/README.md b/README.md
index dd6e366..6208c00 100644
--- a/README.md
+++ b/README.md
@@ -6,11 +6,20 @@
- 
- 
+
+
+
+
+
+
-> A Slash Command handler for discord.js v13
+djs-slash is a command handler for discord.js v13 that provides an easy command definition with file.
+
+**Features**:
+- type checking (with TypeScript)
+- slash command
+- context menu command
## Install
@@ -24,26 +33,90 @@ npm i djs-slash
## How to use
-Commands will be load at runtime from the `commands` folder. Files contains the command. Folder are used to create sub command and sub command group.
+Project architecture example
+```
+├ commands/ (this folder contains all commands)
+| ├ slash/ (slash command)
+| | ├ ping.ts
+| | └ cmd/
+| | ├ subcommand.ts
+| | └ subcommandgroup/
+| | └ subcommand.ts
+| ├ user/ (context menu commands on user)
+| | ├ hi.ts
+| | └ ban.ts
+| └ message/ (context menu commands on message)
+| ├ delete.ts
+| └ repeat.ts
+└ index.ts
+```
-The name of the command is the name of the file (without the extension).
+### Load commands
+```ts
+const commands = SlashCommandManager.create({
+ commandFolder: './commands' // This is the path to the folder where command are stored relative to the entry point of the application (ie the index.ts file)
+});
+// If no parameter is provided, './commands' is used as default path
+const commands = SlashCommandManager.create();
```
-└ commands/
- ├ ping.ts
- └ cmd/
- ├ subcommand.ts
- └ subcommandgroup/
- └ subcommand.ts
+
+
+### Full script example
+
+```ts
+import { Client, Intents } from "discord.js";
+import { SlashCommandManager } from "djs-slash";
+
+const GUILD_ID = '000000000000000000'
+const BOT_TOKEN = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+
+// Create the djs client
+const client = new Client({ intents: [Intents.FLAGS.GUILDS] });
+
+// Load all commands from ./commands/
+const commands = SlashCommandManager.create();
+
+client.once("ready", async (client) => {
+ // Registering commands on a guild
+ const guild = await client.guilds.fetch(GUILD_ID);
+ await guild.commands.set(commands.toApplicationCommandData());
+
+ // Registering commands globally
+ await client.application.commands.set(commands.toApplicationCommandData());
+});
+
+client.on("interactionCreate", async (interaction) => {
+ // Pass the interaction to the SlashCommandManager to execute the command
+ if (await commands.execute(interaction)) {
+ // The interaction trigger a command
+ } else {
+ // The interaction didn't trigger a command.
+ // Either the interaction is not a command interaction
+ // either it didn't correspond to a registred command.
+ }
+});
+
+(async () => {
+ await client.login(BOT_TOKEN);
+})();
```
-Will create the following commands:
+### Define a command
-- `/ping`
-- `/cmd subcommand`
-- `/cmd subcommandgroup subcommand`
+#### Slash command
+Slash command files must be placed in a sub-folder named `slash` inside the command folder.
+The name of the file is the name of the command.
+To create sub-command and sub-command group use folder. Folder name is the name of the command/group.
-### Command file
+ping example:
+```ts
+import { SlashCommand } from 'djs-slash';
+
+export default SlashCommand.define("Reply with 'pong'", {}, async (interaction) => {
+ await interaction.reply({ content: ':ping_pong: pong !', ephemeral: true });
+});
+```
```ts
import { SlashCommand } from "djs-slash";
@@ -86,38 +159,59 @@ export default SlashCommand.define(
);
```
-### index.ts
+`SlashCommand.define(description, options, callback)`
+- `description` `string`: the description of the command.
+- `options` `{ defaultPermission, options }`
+ - [`defaultPermission`](https://discord.js.org/#/docs/main/stable/typedef/ApplicationCommandData) `boolean`: whether the command is enabled by default when the app is added to a guild.
+ - [`options`](https://discord.js.org/#/docs/main/stable/typedef/ApplicationCommandOptionData) `object`: the options of the command, key is the name of the options.
+ - `description` `string`: the description of the option.
+ - `required` `boolean`: whether the option is required.
+ - `type`: the type of the option.
+ - `choices`: the choices of the option for the user to pick from.
+ - `channelTypes`: when the option type is channel, the allowed types of channels that can be selected.
+- `callback` `(interaction, options) => void | Promise`
+ - `interaction` [`CommandInteraction`](https://discord.js.org/#/docs/main/stable/class/CommandInteraction): the interaction object that trigger the command.
+ - `options` `object`: a key-value object where key is the name of the option and the value the value provided by the user.
+
+#### User command
+User command files must be placed in a sub-folder named `user` inside the command folder.
+The name of the file is the name of the command.
+
+An user command example:
```ts
-import { Client, Intents } from "discord.js";
-import { SlashCommandManager } from "djs-slash";
+import { UserCommand } from 'djs-slash';
-// Create the djs client
-const client = new Client({ intents: [Intents.FLAGS.GUILDS] });
+export default UserCommand.define(async (interaction, user) => {
+ await interaction.reply({ content: `Hi, ${user}` });
+});
+```
+`UserCommand.define(callback)`
+- `callback` `(interaction, user) => void | Promise`
+ - `interaction` [`ContextMenuInteraction`](https://discord.js.org/#/docs/main/stable/class/ContextMenuInteraction): the interaction object that trigger the command.
+ - `user` [`User`](https://discord.js.org/#/docs/main/stable/class/User): the target of the command.
-// Load all commands from ./commands/
-const commands = SlashCommandManager.create();
-client.once("ready", async (client) => {
- // Registering commands on a guild
- const guild = await client.guilds.fetch("000000000000000000");
- await guild.commands.set(commands.toApplicationCommandData());
+#### Message command
+Message command files must be placed in a sub-folder named `message` inside the command folder.
+The name of the file is the name of the command.
- // Registering commands globally
- await client.application.commands.set(commands.toApplicationCommandData());
-});
+A message command example:
+```ts
+import { MessageCommand } from 'djs-slash';
-client.on("interactionCreate", async (interaction) => {
- // If the interaction is a command, pass it to the SlashCommandManager to execute the command
- if (interaction.isCommand()) await commands.execute(interaction);
+export default MessageCommand.define(async (interaction, message) => {
+ await interaction.reply({ content: message.content });
});
-
-(async () => {
- await client.login("BOT_TOKEN");
-})();
```
+`MessageCommand.define(callback)`
+- `callback` `(interaction, message) => void | Promise`
+ - `interaction` [`ContextMenuInteraction`](https://discord.js.org/#/docs/main/stable/class/ContextMenuInteraction): the interaction object that trigger the command.
+ - `user` [`Message`](https://discord.js.org/#/docs/main/stable/class/Message): the target of the command.
+
## Example Project
+Checkout the example project to learn more.
To run the example project:
diff --git a/package.json b/package.json
index 995f96c..d9f58cf 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "djs-slash",
"version": "0.1.0",
- "description": "A Slash Command handler for discord.js v13",
+ "description": "An application command handler for discord.js v13",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"scripts": {
@@ -24,7 +24,9 @@
"djs",
"discord",
"slash",
- "command"
+ "command",
+ "context",
+ "menu"
],
"author": {
"name": "Tristan Guichaoua",