feat: precondition guides

.vscode/settings.json

@@ -17,6 +17,7 @@
 		"**/projects/": true,
 	},
 	"cSpell.words": [
-		"favna"
+		"favna",
+		"nsfw"
 	]
 }

docs/Guide/preconditions/channel-types.mdx

@@ -1,6 +1,81 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 title: Setting the types of channel a command can run in
 ---
 
-## TODO
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The [`runIn`][runin] command option can be used to specify the types of channels a command can run in. This can be
+useful if you're developing a command that, for example, displays the roles of a user. In that scenario, you'll want to
+make sure that the command can only be run in guild channels.
+
+:::info
+
+You can view the valid `runIn` values [here][runintypes].
+
+:::
+
+<Tabs groupId="language-choice">
+<TabItem value="javascript" label="JavaScript" default>
+
+```javascript {7}
+const { Command, CommandOptionsRunTypeEnum } = require('@sapphire/framework');
+
+module.exports = class RolesCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      runIn: CommandOptionsRunTypeEnum.GuildAny // Only run in guild channels
+    });
+  }
+};
+```
+
+</TabItem>
+<TabItem value="ESM" label="ESM">
+
+```javascript {7}
+import { Command, CommandOptionsRunTypeEnum } from '@sapphire/framework';
+
+export class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      runIn: CommandOptionsRunTypeEnum.GuildAny // Only run in guild channels
+    });
+  }
+}
+```
+
+</TabItem>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript {7}
+import { Command, CommandOptionsRunTypeEnum } from '@sapphire/framework';
+
+export class PingCommand extends Command {
+  public constructor(context: Command.Context) {
+    super(context, {
+      // ...
+      runIn: CommandOptionsRunTypeEnum.GuildAny // Only run in guild channels
+    });
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+If you try to run a command in direct messages, you'll now find that nothing happens.
+
+:::tip
+
+To learn how to send a message to the command executor when a precondition fails, see [Reporting Precondition
+Failure][reporting-precondition-failure].
+
+:::
+
+[runin]: ../../Documentation/api-framework/interfaces/CommandOptions#runin
+[runintypes]: ../../Documentation/api-framework/enums/CommandOptionsRunTypeEnum
+[reporting-precondition-failure]: ./reporting-precondition-failure

docs/Guide/preconditions/command-cooldown.mdx

@@ -1,6 +1,284 @@
 ---
-sidebar_position: 0
+sidebar_position: 3
 title: Configuring command cooldowns
 ---
 
-## TODO
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Cooldowns are of vital importance for many bots to avoid excessive command usage, API ratelimits, and so on. Luckily,
+Sapphire makes it easy to integrate them into your commands! At its simplest level, cooldowns can be used in specific
+commands via the [`cooldownDelay`][cooldowndelay] property in the command's options. This value is amount of
+milliseconds that a user will have to wait after using a command to use it again. Here's a basic example:
+
+<Tabs groupId="language-choice">
+<TabItem value="javascript" label="JavaScript" default>
+
+```javascript {7}
+const { Command } = require('@sapphire/framework');
+
+module.exports = class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      cooldownDelay: 10_000 // 10_000 milliseconds
+    });
+  }
+};
+```
+
+</TabItem>
+<TabItem value="ESM" label="ESM">
+
+```javascript {7}
+import { Command } from '@sapphire/framework';
+
+export class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      cooldownDelay: 10_000 // 10_000 milliseconds
+    });
+  }
+}
+```
+
+</TabItem>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript {7}
+import { Command } from '@sapphire/framework';
+
+export class PingCommand extends Command {
+  public constructor(context: Command.Context) {
+    super(context, {
+      // ...
+      cooldownDelay: 10_000 // 10_000 milliseconds
+    });
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+If you now try to run this command, and then run it again within 10 seconds, the command won't execute, and an error
+will be thrown. You can learn how to process that error [here][reporting-precondition-failure].
+
+:::info
+
+`cooldownDelay` only accepts a value of milliseconds, which is not known to be the easiest to read or calculate. To
+help, you can use [@sapphire/time-utilities][timeutils], which includes utilities for time transformers.
+
+<Tabs groupId="language-choice">
+<TabItem value="javascript" label="JavaScript" default>
+
+```javascript {7}
+const { Command } = require('@sapphire/framework');
+const { Time } = require('@sapphire/time-utilities');
+
+module.exports = class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      cooldownDelay: Time.Second * 10; // Much easier for humans to read
+    });
+  }
+};
+```
+
+</TabItem>
+<TabItem value="ESM" label="ESM">
+
+```javascript {7}
+import { Command } from '@sapphire/framework';
+import { Time } from '@sapphire/time-utilities';
+
+export class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      cooldownDelay: Time.Second * 10; // Much easier for humans to read
+  }
+}
+```
+
+</TabItem>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript {6}
+import { Command } from '@sapphire/framework';
+import { Time } from '@sapphire/time-utilities';
+
+export class PingCommand extends Command {
+  public constructor(context: Command.Context) {
+    super(context, {
+      // ...
+      cooldownDelay: Time.Second * 10 // Much easier for humans to read
+    });
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+You can view the docs [here][timeenum].
+
+:::
+
+## User Exceptions
+
+It's very common to not want cooldowns to apply to certain people, for example, the bot owner. This can be achieved by
+adding [`cooldownFilteredUsers`][cooldownfilteredusers] to the options. This option should be an array of users ID that
+the bot can ignore when calculating cooldowns.
+
+<Tabs groupId="language-choice">
+<TabItem value="javascript" label="JavaScript" default>
+
+```javascript {8}
+const { Command } = require('@sapphire/framework');
+
+module.exports = class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      cooldownDelay: 10_000, // 10_000 milliseconds
+      cooldownFilteredUsers: ['YOUR_ID'] // Ignore the bot owner
+    });
+  }
+};
+```
+
+</TabItem>
+<TabItem value="ESM" label="ESM">
+
+```javascript {8}
+import { Command } from '@sapphire/framework';
+
+export class PingCommand extends Command {
+  constructor(context) {
+    super(context, {
+      // ...
+      cooldownDelay: 10_000, // 10_000 milliseconds
+      cooldownFilteredUsers: ['YOUR_ID'] // Ignore the bot owner
+    });
+  }
+}
+```
+
+</TabItem>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript {7}
+import { Command } from '@sapphire/framework';
+
+export class PingCommand extends Command {
+  public constructor(context: Command.Context) {
+    super(context, {
+      // ...
+      cooldownDelay: 10_000 // 10_000 milliseconds
+      cooldownFilteredUsers: ['YOUR_ID'] // Ignore the bot owner
+    });
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Advanced Usage
+
+Accompanying `cooldownDelay`, you also have access to the options [`cooldownLimit`][cooldownlimit] and
+[`cooldownScope`][cooldownscope].
+
+`cooldownLimit` will define how many times a command can be used before a cooldown is put into affect. This value is set
+to `1` by default. For example, a `cooldownDelay` of `10_000` milliseconds and a `cooldownLimit` of 2 will effectively
+mean that you'd be able to use the command twice every 10 seconds.
+
+Another useful option is `cooldownScope`, which will define the scope of the cooldown. This is useful if you want to
+have a cooldown that applies per guild, for example, instead of per user. Valid scopes can be found [here][scopes].
+
+## Client-wide Cooldowns
+
+Sometimes you'll find a use case where you want specific cooldown options to apply to all commands in your client. This
+can be achieved by adding [`defaultCooldown`][defaultcooldown] to your [`SapphireClient`][sapphire] options. You can use
+any of the properties shown above with this option.
+
+<Tabs groupId="language-choice">
+<TabItem value="javascript" label="JavaScript" default>
+
+```javascript {5-10}
+const { SapphireClient, BucketScope } = require('@sapphire/framework');
+
+const client = new SapphireClient({
+  intents: ['GUILDS', 'GUILD_MESSAGES'],
+  defaultCooldown: {
+    cooldownDelay: 10_000, // 10_000 milliseconds
+    cooldownFilteredUsers: ['YOUR_ID'], // Ignore the bot owner
+    cooldownLimit: 2, // Allow 2 uses before ratelimiting
+    cooldownScope: BucketScope.Channel // Scope cooldown to channel
+  }
+});
+
+void client.login('your-token-goes-here');
+```
+
+</TabItem>
+<TabItem value="ESM" label="ESM">
+
+```javascript {5-10}
+import { SapphireClient, BucketScope } from '@sapphire/framework';
+
+const client = new SapphireClient({
+  intents: ['GUILDS', 'GUILD_MESSAGES'],
+  defaultCooldown: {
+    cooldownDelay: 10_000, // 10_000 milliseconds
+    cooldownFilteredUsers: ['YOUR_ID'], // Ignore the bot owner
+    cooldownLimit: 2, // Allow 2 uses before ratelimiting
+    cooldownScope: BucketScope.Channel // Scope cooldown to channel
+  }
+});
+
+void client.login('your-token-goes-here');
+```
+
+</TabItem>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript {5-10}
+import { SapphireClient, BucketScope } from '@sapphire/framework';
+
+const client = new SapphireClient({
+  intents: ['GUILDS', 'GUILD_MESSAGES'],
+  defaultCooldown: {
+    cooldownDelay: 10_000, // 10_000 milliseconds
+    cooldownFilteredUsers: ['YOUR_ID'], // Ignore the bot owner
+    cooldownLimit: 2, // Allow 2 uses before ratelimiting
+    cooldownScope: BucketScope.Channel // Scope cooldown to channel
+  }
+});
+
+void client.login('your-token-goes-here');
+```
+
+</TabItem>
+</Tabs>
+
+:::tip
+
+To learn how to send a message to the command executor when a precondition fails, see [Reporting Precondition
+Failure][reporting-precondition-failure].
+
+:::
+
+[cooldowndelay]: ../../Documentation/api-framework/interfaces/CommandOptions#cooldowndelay
+[cooldownfilteredusers]: ../../Documentation/api-framework/interfaces/CommandOptions#cooldownfilteredusers
+[cooldownlimit]: ../../Documentation/api-framework/interfaces/CommandOptions#cooldownlimit
+[cooldownscope]: ../../Documentation/api-framework/interfaces/CommandOptions#cooldownscope
+[defaultcooldown]: ../../Documentation/api-framework/interfaces/SapphireClientOptions#defaultcooldown
+[sapphire]: ../../Documentation/api-framework/classes/SapphireClient
+[scopes]: ../../Documentation/api-framework/enums/BucketScope
+[reporting-precondition-failure]: ./reporting-precondition-failure
+[timeutils]: ../../Documentation/api-utilities/modules/sapphire_time_utilities
+[timeenum]: ../../Documentation/api-utilities/enums/sapphire_time_utilities.Time