@sapphire/discord.js-utilities - npm Package Compare versions

Comparing version 3.0.0-next.99233b4c.0 to 3.0.0-next.a8baab97.0

dist/index.d.ts

@@ -6,2 +6,4 @@ export * from '@sapphire/discord-utilities';
 export * from './lib/type-guards';
+export * from './lib/utilities';
+export * from './lib/utility-types';
 //# sourceMappingURL=index.d.ts.map

dist/lib/MessagePrompter/MessagePrompter.d.ts

@@ -49,2 +49,4 @@ import type { Ctor } from '@sapphire/utilities';
  * ```typescript
+ * const { MessagePrompter } = require('@sapphire/discord.js-utilities');
+ *
  * const handler = new MessagePrompter('Are you sure you want to continue?');
@@ -56,3 +58,5 @@ * const result = await handler.run(channel, author);
  * ```typescript
- * const handler = new MessagePrompter('Choose a number between 5 and 10?', 'number', {
+ * const { MessagePrompter, MessagePrompterStrategies } = require('@sapphire/discord.js-utilities');
+ *
+ * const handler = new MessagePrompter('Choose a number between 5 and 10?', MessagePrompterStrategies.Number, {
  * 		start: 5,
@@ -66,3 +70,5 @@ * 		end: 10
  * ```typescript
- * const handler = new MessagePrompter('Are you happy or sad?', 'reaction', {
+ * const { MessagePrompter, MessagePrompterStrategies } = require('@sapphire/discord.js-utilities');
+ *
+ * const handler = new MessagePrompter('Are you happy or sad?', MessagePrompterStrategies.Reaction, {
  * 		reactions: ['🙂', '🙁']
@@ -75,3 +81,5 @@ * });
  * ```typescript
- * const handler = new MessagePrompter('Do you love me?', 'message');
+ * const { MessagePrompter, MessagePrompterStrategies } = require('@sapphire/discord.js-utilities');
+ *
+ * const handler = new MessagePrompter('Do you love me?', MessagePrompterStrategies.Message);
  * const result = await handler.run(channel, author);
@@ -78,0 +86,0 @@ * ```

dist/lib/PaginatedMessages/PaginatedMessage.d.ts

@@ -16,10 +16,46 @@ import { Awaited } from '@sapphire/utilities';
  * ```typescript
- * const handler = new PaginatedMessage();
+ * const myPaginatedMessage = new PaginatedMessage();
+ * // Once you have an instance of PaginatedMessage you can call various methods on it to add pages to it.
+ * // For more details see each method's documentation.
+ *
+ * myPaginatedMessage.addPageEmbed((embed) => {
+ *		embed
+ *			.setColor('#FF0000')
+ *			.setDescription('example description');
+ *
+ *		return embed;
+ * });
+ *
+ * myPaginatedMessage.addPageBuilder((builder) => {
+ *		const embed = new MessageEmbed()
+ *			.setColor('#FF0000')
+ *			.setDescription('example description');
+ *
+ *		return builder
+ *			.setContent('example content')
+ *			.setEmbed(embed);
+ * });
+ *
+ * myPaginatedMessage.addPageContent('Example');
+ *
+ * myPaginatedMessage.run(message)
  * ```
  *
+ * @remark You can also provide a MessageEmbed template. This will be applied to every page.
+ * If a page itself has an embed then the two will be merged, with the content of
+ * the page's embed taking priority over the template.
+ *
+ * Furthermore, if the template has a footer then it will be applied _after_ the page index part of the footer
+ * with a space preceding the template. For example, when setting `- Powered by Sapphire Framework`
+ * the resulting footer will be `1/2 - Powered by Sapphire Framework`
  * @example
  * ```typescript
- * // To utilize actions you can use the IPaginatedMessageAction by implementing it into a class.
- * // PaginatedMessage requires you to have the class initialized using `new`.
+ * const myPaginatedMessage = new PaginatedMessage({
+ * 	template: new MessageEmbed().setColor('#FF0000').setFooter('- Powered by Sapphire framework')
+ * });
+ * ```
  *
+ * @remark To utilize actions you can implement IPaginatedMessageAction into a class.
+ * @example
+ * ```typescript
  * class ForwardAction implements IPaginatedMessageAction {
@@ -80,6 +116,12 @@ *   public id = '▶️';
     /**
+     * Custom text to show in front of the page index in the embed footer.
+     * PaginatedMessage will automatically add a space (` `) after the given text. You do not have to add it yourself.
+     * @default ```PaginatedMessage.pageIndexPrefix``` (static property)
+     */
+    pageIndexPrefix: string;
+    /**
      * Constructor for the {@link PaginatedMessage} class
      * @param __namedParameters The {@link PaginatedMessageOptions} for this instance of the {@link PaginatedMessage} class
      */
-    constructor({ pages, actions, template }?: PaginatedMessageOptions);
+    constructor({ pages, actions, template, pageIndexPrefix }?: PaginatedMessageOptions);
     setPromptMessage(message: string): this;
@@ -364,3 +406,3 @@ /**
      * @param message The message that triggered this {@link PaginatedMessage}.
-     * Generally this will be the command message, but it can also be another message from your bot, i.e. to indicate a loading state.
+     * Generally this will be the command message, but it can also be another message from your client, i.e. to indicate a loading state.
      * @param target The user who will be able to interact with the reactions of this {@link PaginatedMessage}. Defaults to `message.author`.
@@ -431,5 +473,26 @@ */
      * @default "What page would you like to jump to?"
+     * @remark To overwrite this property change it in a "setup" file prior to calling `client.login()` for your bot.
+     * @example
+     * ```typescript
+     * import { PaginatedMessage } from '@sapphire/discord.js-utilities';
+     *
+     * PaginatedMessage.promptMessage = 'Please send the number of the page you would like to jump to.';
+     * ```
      */
     static promptMessage: string;
     /**
+     * Custom text to show in front of the page index in the embed footer.
+     * PaginatedMessage will automatically add a space (` `) after the given text. You do not have to add it yourself.
+     * @default ""
+     * @remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call `client.login()` for your bot.
+     * @example
+     * ```typescript
+     * import { PaginatedMessage } from '@sapphire/discord.js-utilities';
+     *
+     * PaginatedMessage.pageIndexPrefix = 'Page';
+     * // This will make the footer of the embed something like "Page 1/2"
+     * ```
+     */
+    static pageIndexPrefix: string;
+    /**
      * The messages that are currently being handled by a {@link PaginatedMessage}
@@ -506,2 +569,6 @@ * The key is the ID of the message that triggered this {@link PaginatedMessage}
     template?: MessageEmbed | MessageOptions;
+    /**
+     * @seealso {@link PaginatedMessage.pageIndexPrefix}
+     */
+    pageIndexPrefix?: string;
 }
@@ -511,43 +578,16 @@ /**
  *
- * Pages can be either an {@link MessagePayload} directly,
- * or an awaited function which returns an {@link MessagePayload}.
+ * Pages can be either a {@link MessagePayload},
+ * or an awaited function that returns a {@link MessagePayload}.
  *
  * Furthermore, {@link MessageOptions} can be used to
- * construct the pages without state, this library also provides {@link MessageBuilder}, which can be used as a chainable
+ * construct the pages without state. This library also provides {@link MessageBuilder}, which can be used as a chainable
  * alternative to raw objects, similar to how {@link MessageEmbed}
  * works.
  *
- * @example
- * ```typescript
- * // Direct usage as a MessageBuilder
- * new MessageBuilder().setContent('Test content!');
- * ```
- *
- * @example
- * ```typescript
- * // An awaited function. This function also passes index, pages, and handler.
- * (index, pages) =>
- *   new MessageBuilder().setEmbed(
- *     new MessageEmbed().setFooter(`Page ${index + 1} / ${pages.length}`)
- *   );
- * ```
- *
- * @example
- * ```typescript
- * // Direct usage as an MessagePayload
- * new MessagePayload(message.channel, {
- *   content: 'Test content!',
- * });
- * ```
- *
- * @example
- * ```typescript
- * // An awaited function. This function also passes index, pages, and handler.
- * (index, pages) =>
- *   new MessagePayload(message.channel, {
- *     embed: new MessageEmbed().setFooter(`Page ${index + 1} / ${pages.length}`)
- *   });
- * ```
+ * Ideally, however, you should use the utility functions
+ * {@link PaginatedMessage.addPageBuilder `addPageBuilder`}, {@link PaginatedMessage.addPageContent `addPageContent`}, and {@link PaginatedMessage.addPageEmbed `addPageEmbed`}
+ * as opposed to manually constructing {@link MessagePage `MessagePages`}. This is because a {@link PaginatedMessage} does a lot of post-processing
+ * on the provided pages and we can only guarantee this will work properly when using the utility methods.
  */
 export declare type MessagePage = ((index: number, pages: MessagePage[], handler: PaginatedMessage) => Awaited<MessagePayload | MessageOptions>) | MessagePayload | MessageOptions;
 //# sourceMappingURL=PaginatedMessage.d.ts.map

dist/lib/type-guards.d.ts

@@ -1,2 +0,3 @@
-import type { CategoryChannel, Channel, DMChannel, GuildChannel, NewsChannel, PartialGroupDMChannel, StageChannel, StoreChannel, TextChannel, VoiceChannel } from 'discord.js';
+import type { CategoryChannel, Channel, DMChannel, NewsChannel, PartialGroupDMChannel, StageChannel, StoreChannel, TextChannel, ThreadChannel, VoiceChannel } from 'discord.js';
+import type { ChannelTypes, GuildTextBasedChannelTypes, TextBasedChannelTypes } from './utility-types';
 /**
@@ -6,3 +7,3 @@ * Checks whether a given channel is a {@link CategoryChannel}
  */
-export declare function isCategoryChannel(channel: Channel): channel is CategoryChannel;
+export declare function isCategoryChannel(channel: ChannelTypes): channel is CategoryChannel;
 /**
@@ -12,3 +13,3 @@ * Checks whether a given channel is a {@link DMChannel}
  */
-export declare function isDMChannel(channel: Channel): channel is DMChannel;
+export declare function isDMChannel(channel: ChannelTypes): channel is DMChannel;
 /**
@@ -20,21 +21,29 @@ * Checks whether a given channel is a {@link PartialGroupDMChannel}
 /**
- * Checks whether a given channel is a {@link GuildChannel}
+ * Checks if a channel comes from a guild.
  * @param channel The channel to check
+ * @returns Whether or not the channel is guild-based.
  */
-export declare function isGuildBasedChannel(channel: Channel): channel is GuildChannel;
+export declare function isGuildBasedChannel(channel: ChannelTypes): channel is GuildTextBasedChannelTypes;
 /**
- * Checks whether a given channel is a {@link NewsChannel}
- * @param channel The channel to check
+ * Checks whether or not a channel comes from a guild.
+ * @remark As opposed to {@link isGuildBasedChannel} this checks if there is `guild` property on the channel.
+ * @param channel The channel to check.
+ * @returns Whether or not the channel is guild-based.
  */
-export declare function isNewsChannel(channel: Channel): channel is NewsChannel;
+export declare function isGuildBasedChannelByGuildKey(channel: ChannelTypes): channel is GuildTextBasedChannelTypes;
 /**
+ * Checks whether a given channel is a {@link NewsChannel}.
+ * @param channel The channel to check.
+ */
+export declare function isNewsChannel(channel: ChannelTypes): channel is NewsChannel;
+/**
  * Checks whether a given channel is a {@link StoreChannel}
  * @param channel The channel to check
  */
-export declare function isStoreChannel(channel: Channel): channel is StoreChannel;
+export declare function isStoreChannel(channel: ChannelTypes): channel is StoreChannel;
 /**
- * Checks whether a given channel is a {@link TextChannel}
- * @param channel The channel to check
+ * Checks whether a given channel is a {@link TextChannel}.
+ * @param channel The channel to check.
  */
-export declare function isTextChannel(channel: Channel): channel is TextChannel;
+export declare function isTextChannel(channel: ChannelTypes): channel is TextChannel;
 /**
@@ -44,3 +53,3 @@ * Checks whether a given channel is a {@link VoiceChannel}
  */
-export declare function isVoiceChannel(channel: Channel): channel is VoiceChannel;
+export declare function isVoiceChannel(channel: ChannelTypes): channel is VoiceChannel;
 /**
@@ -50,3 +59,13 @@ * Checks whether a given channel is a {@link StageChannel}
  */
-export declare function isStageChannel(channel: Channel): channel is StageChannel;
+export declare function isStageChannel(channel: ChannelTypes): channel is StageChannel;
+/**
+ * Checks whether a given channel is a {@link ThreadChannel}
+ * @param channel The channel to check.
+ */
+export declare function isThreadChannel(channel: ChannelTypes): channel is ThreadChannel;
+/**
+ * Checks whether a given channel allows NSFW content or not
+ * @param channel The channel to check.
+ */
+export declare function isNsfwChannel(channel: TextBasedChannelTypes): boolean;
 //# sourceMappingURL=type-guards.d.ts.map

package.json

 {
 	"name": "@sapphire/discord.js-utilities",
-	"version": "3.0.0-next.99233b4c.0",
+	"version": "3.0.0-next.a8baab97.0",
 	"description": "Discord.js specific utilities for your JavaScript/TypeScript bots",
@@ -32,4 +32,4 @@ "author": "@sapphire",
 	"engines": {
-		"node": ">=14",
-		"npm": ">=6"
+		"node": ">=16.6.0",
+		"npm": ">=7"
 	},
@@ -54,7 +54,7 @@ "keywords": [
 	"dependencies": {
-		"@sapphire/discord-utilities": "^2.1.5",
-		"@sapphire/time-utilities": "^1.3.8",
-		"@sapphire/utilities": "^2.0.1"
+		"@sapphire/discord-utilities": "^2.2.0-next.a8baab97.0",
+		"@sapphire/time-utilities": "^1.4.0-next.a8baab97.0",
+		"@sapphire/utilities": "^2.1.0-next.a8baab97.0"
 	},
-	"gitHead": "99233b4ca2b214c7ad47b1a918256cc6f9532acc"
+	"gitHead": "a8baab978814ca3aa18992120af7ad004ceaee80"
 }

No alert changes

Improved metrics

Total package byte prevSize

413142

increased by7.03%

Number of package files

43

increased by10.26%

Lines of code

4499

increased by10.05%

Dependency changes

• + Added@sapphire/[e-mail]7a606.0(transitive)

• - Removed@sapphire/utilities@2.0.1(transitive)

• Updated@sapphire/discord-utilities@^2.2.0-next.a8baab97.0

• Updated@sapphire/time-utilities@^1.4.0-next.a8baab97.0

• Updated@sapphire/utilities@^2.1.0-next.a8baab97.0