Skip to content

Commit 5729bbd

Browse files
notunderctrlnotunderctrl
committed
add typescript guides
1 parent 1120a58 commit 5729bbd

File tree

5 files changed

+153
-13
lines changed

5 files changed

+153
-13
lines changed

‎apps/docs/astro.config.mjs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,10 @@ export default defineConfig({
4747
},
4848
],
4949
},
50-
typeDocSidebarGroup,
50+
{
51+
...typeDocSidebarGroup,
52+
label: 'Reference',
53+
},
5154
],
5255
}),
5356
],

‎apps/docs/src/content/docs/guides/command-file-setup.mdx‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ This is a simple overview of how to set up a simple "ping" slash command that si
2121
description: 'Pong!',
2222
},
2323

24-
run: ({ interaction, client }) => {
24+
run: ({ interaction, client, handler }) => {
2525
interaction.reply(`:ping_pong: Pong! ${client.ws.ping}ms`);
2626
},
2727

@@ -44,7 +44,7 @@ This is a simple overview of how to set up a simple "ping" slash command that si
4444
description: 'Pong!',
4545
},
4646

47-
export function run({ interaction, client }) {
47+
export function run({ interaction, client, handler }) {
4848
interaction.reply(`:ping_pong: Pong! ${client.ws.ping}ms`);
4949
},
5050

@@ -57,6 +57,30 @@ This is a simple overview of how to set up a simple "ping" slash command that si
5757
},
5858
```
5959
</TabItem>
60+
61+
<TabItem label="TypeScript">
62+
```ts
63+
// commands/misc/ping.ts
64+
import type { CommandData, SlashCommandProps, CommandOptions } from 'commandkit';
65+
66+
export const data: CommandData = {
67+
name: 'ping',
68+
description: 'Pong!',
69+
},
70+
71+
export function run({ interaction, client, handler }: SlashCommandProps) {
72+
interaction.reply(`:ping_pong: Pong! ${client.ws.ping}ms`);
73+
},
74+
75+
export const options: CommandOptions = {
76+
devOnly: true,
77+
guildOnly: true,
78+
userPermissions: ['Administrator', 'AddReactions'],
79+
botPermissions: ['Administrator', 'AddReactions'],
80+
deleted: false,
81+
},
82+
```
83+
</TabItem>
6084

6185
</Tabs>
6286

@@ -69,14 +93,15 @@ Every command file must export an object with the following properties:
6993
This can also be set to the [`SlashCommandBuilder`](https://discord.js.org/docs/packages/builders/0.16.0/SlashCommandBuilder:Class) class, or the [`ContextMenuCommandBuilder`](https://discord.js.org/docs/packages/builders/0.16.0/ContextMenuCommandBuilder:Class) class if that's what you're comfortable with.
7094

7195
- `run` - A function that will be called when your command is executed. This function also has an object passed to it as an argument with the following properties:
72-
- `interaction` - The interaction object that triggered the command. This can either be a chat input interaction or a context menu interaction.
73-
- `client` - The Discord client object.
96+
- `interaction` - The interaction object that triggered the command. This can either be a [chat input command interaction](https://old.discordjs.dev/#/docs/discord.js/main/class/ChatInputCommandInteraction) or a [context menu command interaction](https://old.discordjs.dev/#/docs/discord.js/main/class/ContextMenuCommandInteraction).
97+
- `client` - The Discord [client object](https://old.discordjs.dev/#/docs/discord.js/main/class/Client).
98+
- `handler` - The current [CommandKit instance](/api/classes/classcommandkit/).
7499

75100
### Optional properties
76101

77102
There is an additional optional property that can also be exported within the object above:
78103

79-
- `options` - An object which tells the command how to behave during registration and handling. This object has the following optional properties:
104+
- [`options`](/api/interfaces/interfacecommandoptions/) - An object which tells the command how to behave during registration and handling. This object has the following optional properties:
80105
- `devOnly` - A boolean that determines whether the command should only be registered in development guilds and be executed by the bot developers. These properties are setup as `devGuildIds`, `devUserIds`, and `devRoleIds` when [instantiating `CommandKit`](/guides/commandkit-setup/).
81106
- `guildOnly` - A boolean that determines whether the command should only be handled in guilds.
82107
- `userPermissions` - An array of permission strings/bits that determines whether the user has the required permissions to execute the command. This is checked against the user's permissions in the guild where the command was executed (if any).

‎apps/docs/src/content/docs/guides/commandkit-setup.mdx‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,39 @@ This is a simple overview of how to set up CommandKit with all the available opt
7272
client.login('YOUR_TOKEN_HERE');
7373
```
7474
</TabItem>
75+
76+
<TabItem label="TypeScript">
77+
```js
78+
// index.ts
79+
import { Client, GatewayIntentBits } from 'discord.js';
80+
import { CommandKit } from 'commandkit';
81+
import { fileURLToPath } from 'url';
82+
import path from 'path';
83+
84+
const client = new Client({
85+
intents: [
86+
GatewayIntentBits.Guilds,
87+
GatewayIntentBits.GuildMessages,
88+
GatewayIntentBits.MessageContent
89+
],
90+
});
91+
92+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
93+
94+
new CommandKit({
95+
client,
96+
commandsPath: path.join(__dirname, 'commands'),
97+
eventsPath: path.join(__dirname, 'events'),
98+
validationsPath: path.join(__dirname, 'validations'),
99+
devGuildIds: ['DEV_SERVER_ID_1', 'DEV_SERVER_ID_2'],
100+
devUserIds: ['DEV_USER_ID_1', 'DEV_USER_ID_2'],
101+
devRoleIds: ['DEV_ROLE_ID_1', 'DEV_ROLE_ID_2'],
102+
skipBuiltInValidations: true,
103+
});
104+
105+
client.login('YOUR_TOKEN_HERE');
106+
```
107+
</TabItem>
75108
76109
</Tabs>
77110
@@ -96,7 +129,7 @@ constructor, a [list of intents can be found here](https://discord-api-types.dev
96129
- `devGuildIds` - Array of development server IDs. Used to register and run developer only commands in specific servers.
97130
- `devUserIds` - Array of developer user IDs. Used to ensure developer only commands can only be ran by these users.
98131
- `devRoleIds` - Array of developer role IDs. Used to ensure developer only commands can only be ran by users with these roles.
99-
- `skipBuiltInValidations` - A property that disables CommandKit's built-in validations.
132+
- `skipBuiltInValidations` - A property that disables CommandKit's built-in validations. These validations are responsible for handling the default behaviour of the [`options`](/api/interfaces/interfacecommandoptions/) property in commands.
100133
101134
:::note
102135
It's highly recommended to use the "path" library to define your paths to avoid any file import issues.

‎apps/docs/src/content/docs/guides/event-file-setup.mdx‎

Lines changed: 58 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ This is a simple overview of how to set up a simple function that is called when
1313
<TabItem label="CommonJS">
1414
```js
1515
// events/ready/console-log.js
16-
module.exports = (c, client) => {
16+
module.exports = (c, client, handler) => {
1717
console.log(`${c.user.username} is ready!`);
1818
};
1919
```
@@ -22,7 +22,19 @@ This is a simple overview of how to set up a simple function that is called when
2222
<TabItem label="ESM">
2323
```js
2424
// events/ready/console-log.js
25-
export default function (c, client) {
25+
export default function (c, client, handler) {
26+
console.log(`${c.user.username} is ready!`);
27+
};
28+
```
29+
</TabItem>
30+
31+
<TabItem label="TypeScript">
32+
```ts
33+
// events/ready/console-log.ts
34+
import type { Client } from 'discord.js';
35+
import type { CommandKit } from 'commandkit';
36+
37+
export default function (c: Client<true>, client: Client<true>, handler: CommandKit) {
2638
console.log(`${c.user.username} is ready!`);
2739
};
2840
```
@@ -31,7 +43,7 @@ This is a simple overview of how to set up a simple function that is called when
3143

3244
### Parameters explained
3345

34-
The parameters might look a bit confusing at first, but they're actually quite simple. The first parameter `c` is the client object that was returned as a parameter when the "ready" event was triggered. The second parameter `client` is the Discord.js client that was instantiated in your main entry point file.
46+
The parameters might look a bit confusing at first, but they're actually quite simple. The first parameter `c` is the client object that was returned as a parameter when the "ready" event was triggered. The second parameter `client` is the Discord.js client that was instantiated in your main entry point file. Finally, the `handler` parameter is the [CommandKit instance](/api/classes/classcommandkit/).
3547

3648
To better understand how the parameters work, here's another example but with the "messageCreate" event listener.
3749

@@ -50,7 +62,21 @@ To better understand how the parameters work, here's another example but with th
5062
<TabItem label="ESM">
5163
```js
5264
// events/messageCreate/say-hi.js
53-
export default function (message, client) {
65+
export default function (message, client, handler) {
66+
if (message.content === 'hey') {
67+
message.reply('Hi!');
68+
}
69+
};
70+
```
71+
</TabItem>
72+
73+
<TabItem label="TypeScript">
74+
```ts
75+
// events/messageCreate/say-hi.ts
76+
import type { Message, Client } from 'discord.js';
77+
import type { CommandKit } from 'commandkit';
78+
79+
export default function (message: Message<true>, client: Client<true>, handler: CommandKit) {
5480
if (message.content === 'hey') {
5581
message.reply('Hi!');
5682
}
@@ -83,6 +109,18 @@ But what if an event returns multiple parameters? Let's take for example the "me
83109
};
84110
```
85111
</TabItem>
112+
113+
<TabItem label="TypeScript">
114+
```js
115+
// events/messageUpdate/log-message-update.ts
116+
import type { Message, PartialMessage } from 'discord.js';
117+
import type { CommandKit } from 'commandkit';
118+
119+
export default function (oldMessage: Message<boolean> | PartialMessage, newMessage: Message<boolean> | PartialMessage, client: Client<true>, handler: CommandKit) {
120+
console.log(`Message edited from ${oldMessage.content} to ${newMessage.content}`);
121+
};
122+
```
123+
</TabItem>
86124

87125
</Tabs>
88126

@@ -118,6 +156,22 @@ The code above is just a simple example of how to set up an event function. But
118156
}
119157
```
120158
</TabItem>
159+
160+
<TabItem label="TypeScript">
161+
```js
162+
// events/messageCreate/say-hi.ts
163+
import type { Message, Client } from 'discord.js';
164+
import type { CommandKit } from 'commandkit';
165+
166+
export default function (message: Message<true>, client: Client<true>, handler: CommandKit) {
167+
if (message.content === 'hey') {
168+
message.reply('Hi!')
169+
170+
return true // THIS STOPS THE EVENT LOOP
171+
}
172+
}
173+
```
174+
</TabItem>
121175

122176
</Tabs>
123177

‎apps/docs/src/content/docs/guides/validation-file-setup.mdx‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,17 @@ Validations are functions that are called before the `run()` function from a com
1111

1212
Validation functions are called on every command trigger, so it's important to keep them as lightweight as possible.
1313

14+
:::note
15+
Custom validation functions are called before the built-in validations provided by CommandKit. This provides you with more control over the flow of commands.
16+
:::
17+
1418
<Tabs>
1519
<TabItem label="CommonJS">
1620
```js
1721
// validations/cooldowns.js
1822
const cooldowns = require('../cooldowns-cache');
1923

20-
module.exports = ({ interaction, commandObj }) => {
24+
module.exports = ({ interaction, commandObj, handler }) => {
2125
if (cooldowns.has(`${interaction.user.id}-${commandObj.data.name}`)) {
2226
interaction.reply({
2327
content: "You're on cooldown, please wait some time before running this command again.",
@@ -35,7 +39,26 @@ Validation functions are called on every command trigger, so it's important to k
3539
// validations/cooldowns.js
3640
import cooldowns from '../cooldowns-cache';
3741

38-
export default function ({ interaction, commandObj }) {
42+
export default function ({ interaction, commandObj, handler }) {
43+
if (cooldowns.has(`${interaction.user.id}-${commandObj.data.name}`)) {
44+
interaction.reply({
45+
content: "You're on cooldown, please wait some time before running this command again.",
46+
ephemeral: true,
47+
});
48+
49+
return true; // THIS IS IMPORTANT
50+
}
51+
};
52+
```
53+
</TabItem>
54+
55+
<TabItem label="TypeScript">
56+
```js
57+
// validations/cooldowns.js
58+
import type { ValidationFunctionProps } from 'commandkit';
59+
import cooldowns from '../cooldowns-cache';
60+
61+
export default function ({ interaction, commandObj, handler }: ValidationFunctionProps) {
3962
if (cooldowns.has(`${interaction.user.id}-${commandObj.data.name}`)) {
4063
interaction.reply({
4164
content: "You're on cooldown, please wait some time before running this command again.",
@@ -56,6 +79,8 @@ Within every validation function, you have the ability to check what command is
5679

5780
The `commandObj` object is what's being exported from your command file (excluding the `run()` function). This means you can access the `data` and `options` property from within your validation function.
5881

82+
The `handler` object is your [CommandKit instance](/api/classes/classcommandkit/).
83+
5984
### Stopping the command from running
6085

6186
You may notice that the code above is returning `true`. This is important as it tells the command handler to not run any other validations and to not run the command. If you do not return `true` (or any truthy value), the command will run as normal.

0 commit comments

Comments
 (0)