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

Comparing version 1.0.1 to 1.1.0

CHANGELOG.md

@@ -6,2 +6,8 @@ # Change Log
 
+# [1.1.0](https://github.com/sapphire-project/utilities/compare/@sapphire/discord.js-utilities@1.0.1...@sapphire/discord.js-utilities@1.1.0) (2021-01-13)
+
+### Features
+
+-   **discord.js-utilities:** add checking index changes and documentation ([#57](https://github.com/sapphire-project/utilities/issues/57)) ([8d99797](https://github.com/sapphire-project/utilities/commit/8d99797968af72fa02958d80eebcfc92a1cb3c2d))
+
 ## [1.0.1](https://github.com/sapphire-project/utilities/compare/@sapphire/discord.js-utilities@1.0.0...@sapphire/discord.js-utilities@1.0.1) (2021-01-08)
@@ -8,0 +14,0 @@

dist/index.js

@@ -1,2 +0,2 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@sapphire/discord-utilities");class PaginatedMessage{constructor({pages:e,actions:t=PaginatedMessage.defaultActions}={}){Object.defineProperty(this,"pages",{enumerable:!0,configurable:!0,writable:!0,value:void 0}),Object.defineProperty(this,"messages",{enumerable:!0,configurable:!0,writable:!0,value:[]}),Object.defineProperty(this,"actions",{enumerable:!0,configurable:!0,writable:!0,value:new Map}),Object.defineProperty(this,"index",{enumerable:!0,configurable:!0,writable:!0,value:0}),Object.defineProperty(this,"idle",{enumerable:!0,configurable:!0,writable:!0,value:2e4}),this.pages=null!=e?e:[];for(const e of this.pages)this.messages.push("function"==typeof e?null:e);for(const e of t)this.actions.set(e.id,e)}setIndex(e){return this.index=e,this}setIdle(e){return this.idle=e,this}setActions(e){return this.actions.clear(),this.addActions(e)}addActions(e){for(const t of e)this.addAction(t);return this}addAction(e){return this.actions.set(e.id,e),this}setPages(e){return this.pages=[],this.messages=[],this.addPages(e),this}addPages(e){for(const t of e)this.addPage(t);return this}addPage(e){return this.pages.push(e),this.messages.push("function"==typeof e?null:e),this}async run(e,t){if(await this.resolvePagesOnRun(),!this.messages.length)throw new Error("There are no messages.");if(!this.actions.size)throw new Error("There are no messages.");const s=this.messages[this.index],n=await t.send(s);for(const e of this.actions.keys())await n.react(e);const a=n.createReactionCollector(((t,s)=>(this.actions.has(t.emoji.identifier)||this.actions.has(t.emoji.name))&&s.id===e.id),{idle:this.idle}).on("collect",(async(s,i)=>{var r;await s.users.remove(i);const o=null!==(r=this.actions.get(s.emoji.identifier))&&void 0!==r?r:this.actions.get(s.emoji.name);await o.run({handler:this,author:e,channel:t,response:n,collector:a});const l=await this.resolvePage();await n.edit(l)})).on("end",(()=>n.reactions.removeAll()));return this}async resolvePagesOnRun(){for(let e=0;e<this.pages.length;e++)await this.resolvePage(e)}async resolvePage(e=this.index){var t,s;return this.pages[e]&&(null!==(t=(s=this.messages)[e])&&void 0!==t||(s[e]=await this.pages[e](e,this.pages,this))),this.messages[e]}clone(){const e=new PaginatedMessage({pages:this.pages,actions:[]}).setIndex(this.index).setIdle(this.idle);return e.actions=this.actions,e}}Object.defineProperty(PaginatedMessage,"defaultActions",{enumerable:!0,configurable:!0,writable:!0,value:[{id:"🔢",run:async({handler:e,author:t,channel:s})=>{const n=await s.send("What page would you like to jump to?"),a=await s.awaitMessages((e=>e.author.id===t.id),{max:1,idle:15e3}).catch((()=>null));if(a){const t=a.first();if(n.deletable&&await n.delete(),t){t.deletable&&await t.delete();const s=Number(t.content)-1;!Number.isNaN(s)&&e.pages[s]&&(e.index=s)}}}},{id:"⏪",run:({handler:e})=>e.index=0},{id:"◀️",run:({handler:e})=>{0!==e.index&&--e.index}},{id:"▶️",run:({handler:e})=>{e.index!==e.pages.length-1&&++e.index}},{id:"⏩",run:({handler:e})=>e.index=e.pages.length-1},{id:"⏹️",run:async({response:e,collector:t})=>{await e.reactions.removeAll(),t.stop()}}]});Object.keys(e).forEach((function(t){"default"!==t&&Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})})),exports.LazyPaginatedMessage=class LazyPaginatedMessage extends PaginatedMessage{async resolvePagesOnStart(){await this.resolvePage(this.index)}async resolvePage(e=this.index){return await super.resolvePage(e-1),await super.resolvePage(e+1),super.resolvePage(e)}},exports.PaginatedMessage=PaginatedMessage,exports.isCategoryChannel=function isCategoryChannel(e){return"category"===e.type},exports.isDMChannel=function isDMChannel(e){return"dm"===e.type},exports.isGroupChannel=function isGroupChannel(e){return"group"===e.type},exports.isGuildBasedChannel=function isGuildBasedChannel(e){return"dm"!==e.type&&"group"!==e.type&&"unknown"!==e.type},exports.isNewsChannel=function isNewsChannel(e){return"news"===e.type},exports.isStoreChannel=function isStoreChannel(e){return"store"===e.type},exports.isTextChannel=function isTextChannel(e){return"text"===e.type},exports.isVoiceChannel=function isVoiceChannel(e){return"voice"===e.type};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@sapphire/discord-utilities");class PaginatedMessage{constructor({pages:e,actions:t=PaginatedMessage.defaultActions}={}){Object.defineProperty(this,"pages",{enumerable:!0,configurable:!0,writable:!0,value:void 0}),Object.defineProperty(this,"messages",{enumerable:!0,configurable:!0,writable:!0,value:[]}),Object.defineProperty(this,"actions",{enumerable:!0,configurable:!0,writable:!0,value:new Map}),Object.defineProperty(this,"index",{enumerable:!0,configurable:!0,writable:!0,value:0}),Object.defineProperty(this,"idle",{enumerable:!0,configurable:!0,writable:!0,value:2e4}),this.pages=null!=e?e:[];for(const e of this.pages)this.messages.push("function"==typeof e?null:e);for(const e of t)this.actions.set(e.id,e)}setIndex(e){return this.index=e,this}setIdle(e){return this.idle=e,this}setActions(e){return this.actions.clear(),this.addActions(e)}addActions(e){for(const t of e)this.addAction(t);return this}addAction(e){return this.actions.set(e.id,e),this}setPages(e){return this.pages=[],this.messages=[],this.addPages(e),this}addPages(e){for(const t of e)this.addPage(t);return this}addPage(e){return this.pages.push(e),this.messages.push("function"==typeof e?null:e),this}async run(e,t){if(await this.resolvePagesOnRun(),!this.messages.length)throw new Error("There are no messages.");if(!this.actions.size)throw new Error("There are no messages.");const s=this.messages[this.index],n=await t.send(s);for(const e of this.actions.keys())await n.react(e);const i=n.createReactionCollector(((t,s)=>(this.actions.has(t.emoji.identifier)||this.actions.has(t.emoji.name))&&s.id===e.id),{idle:this.idle}).on("collect",(async(s,a)=>{var r;await s.users.remove(a);const o=null!==(r=this.actions.get(s.emoji.identifier))&&void 0!==r?r:this.actions.get(s.emoji.name),l=this.index;if(await o.run({handler:this,author:e,channel:t,response:n,collector:i}),l!==this.index){const e=await this.resolvePage();await n.edit(e)}})).on("end",(()=>n.reactions.removeAll()));return this}async resolvePagesOnRun(){for(let e=0;e<this.pages.length;e++)await this.resolvePage(e)}async resolvePage(e=this.index){var t,s;return this.pages[e]&&(null!==(t=(s=this.messages)[e])&&void 0!==t||(s[e]=await this.pages[e](e,this.pages,this))),this.messages[e]}clone(){const e=new PaginatedMessage({pages:this.pages,actions:[]}).setIndex(this.index).setIdle(this.idle);return e.actions=this.actions,e}}Object.defineProperty(PaginatedMessage,"defaultActions",{enumerable:!0,configurable:!0,writable:!0,value:[{id:"🔢",run:async({handler:e,author:t,channel:s})=>{const n=await s.send("What page would you like to jump to?"),i=await s.awaitMessages((e=>e.author.id===t.id),{max:1,idle:15e3}).catch((()=>null));if(i){const t=i.first();if(n.deletable&&await n.delete(),t){t.deletable&&await t.delete();const s=Number(t.content)-1;!isNaN(s)&&e.pages[s]&&(e.index=s)}}}},{id:"⏪",run:({handler:e})=>e.index=0},{id:"◀️",run:({handler:e})=>{0!==e.index&&--e.index}},{id:"▶️",run:({handler:e})=>{e.index!==e.pages.length-1&&++e.index}},{id:"⏩",run:({handler:e})=>e.index=e.pages.length-1},{id:"⏹️",run:async({response:e,collector:t})=>{await e.reactions.removeAll(),t.stop()}}]});Object.keys(e).forEach((function(t){"default"!==t&&Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})})),exports.LazyPaginatedMessage=class LazyPaginatedMessage extends PaginatedMessage{async resolvePagesOnStart(){await this.resolvePage(this.index)}async resolvePage(e=this.index){return await super.resolvePage(e-1),await super.resolvePage(e+1),super.resolvePage(e)}},exports.PaginatedMessage=PaginatedMessage,exports.isCategoryChannel=function isCategoryChannel(e){return"category"===e.type},exports.isDMChannel=function isDMChannel(e){return"dm"===e.type},exports.isGroupChannel=function isGroupChannel(e){return"group"===e.type},exports.isGuildBasedChannel=function isGuildBasedChannel(e){return"dm"!==e.type&&"group"!==e.type&&"unknown"!==e.type},exports.isNewsChannel=function isNewsChannel(e){return"news"===e.type},exports.isStoreChannel=function isStoreChannel(e){return"store"===e.type},exports.isTextChannel=function isTextChannel(e){return"text"===e.type},exports.isVoiceChannel=function isVoiceChannel(e){return"voice"===e.type};
 //# sourceMappingURL=index.js.map

dist/lib/LazyPaginatedMessage.d.ts

 /// <reference types="discord.js" />
 import { PaginatedMessage } from './PaginatedMessage';
+/**
+ * This is a LazyPaginatedMessage. Instead of resolving all pages that are functions on [[PaginatedMessage.run]] will resolve when requested.
+ */
 export declare class LazyPaginatedMessage extends PaginatedMessage {
+    /**
+     * Only resolves the page corresponding with the handler's current index.
+     */
     resolvePagesOnStart(): Promise<void>;
+    /**
+     * Resolves the page corresponding with the given index. This also resolves the index's before and after the given index.
+     * @param index The index to resolve. Defaults to handler's current index.
+     */
     resolvePage(index?: number): Promise<import("discord.js").APIMessage | null>;
 }
 //# sourceMappingURL=LazyPaginatedMessage.d.ts.map

dist/lib/PaginatedMessage.d.ts

 import type { APIMessage, User, TextChannel, NewsChannel, Message, ReactionCollector } from 'discord.js';
+/**
+ * This is a [[PaginatedMessage]], a utility to paginate messages (usually embeds).
+ * You must either use this class directly or extend it.
+ *
+ * [[PaginatedMessage]] uses actions, these are essentially reaction emojis, when triggered run the said action.
+ * You can utilize your own actions, or you can use the [[PaginatedMessage.defaultActions]].
+ * [[PaginatedMessage.defaultActions]] is also static so you can modify these directly.
+ *
+ * [[PaginatedMessage]] also uses pages, these are simply {@link https://discord.js.org/#/docs/main/stable/class/APIMessage APIMessages}.
+ *
+ * @example
+ * ```typescript
+ * const handler = new PaginatedMessage();
+ * ```
+ *
+ * @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`.
+ *
+ * class ForwardAction implements IPaginatedMessageAction {
+ *   public id = '▶️';
+ *
+ *   public run({ handler }) {
+ *     if (handler.index !== handler.pages.length - 1) ++handler.index;
+ *   }
+ * }
+ *
+ * // You can also give the object directly.
+ *
+ * const StopAction: IPaginatedMessageAction {
+ *   id: '⏹️',
+ *   disableResponseEdit: true,
+ *   run: ({ response, collector }) => {
+ *     await response!.reactions.removeAll();
+ *     collector!.stop();
+ *   }
+ * }```
+ *
+ */
 export declare class PaginatedMessage {
+    /**
+     * The pages to be converted to [[PaginatedMessage.messages]]
+     */
     pages: MessagePage[];
+    /**
+     * The pages which were converted from [[PaginatedMessage.pages]]
+     */
     messages: (APIMessage | null)[];
+    /**
+     * The actions which are to be used.
+     */
     actions: Map<string, IPaginatedMessageAction>;
+    /**
+     * The handler's current page/message index.
+     */
     index: number;
+    /**
+     * The amount of time to idle before the paginator is closed. Defaults to `20 * 1000`.
+     */
     idle: number;
+    /**
+     * Constructor for the [[PaginatedMessage]] class
+     * @param __namedParameters The [[PaginatedMessageOptions]] for this instance of the [[PaginatedMessage]] class
+     */
     constructor({ pages, actions }?: PaginatedMessageOptions);
+    /**
+     * Sets the handler's current page/message index.
+     * @param index The number to set the index to.
+     */
     setIndex(index: number): this;
+    /**
+     * Sets the amount of time to idle before the paginator is closed.
+     * @param idle The number to set the idle to.
+     */
     setIdle(idle: number): this;
+    /**
+     * Clears all current actions and sets them. The order given is the order they will be used.
+     * @param actions The actions to set.
+     */
     setActions(actions: IPaginatedMessageAction[]): this;
+    /**
+     * Adds actions to the existing ones. The order given is the order they will be used.
+     * @param actions The actions to add.
+     */
     addActions(actions: IPaginatedMessageAction[]): this;
+    /**
+     * Adds an action to the existing ones. This will be added as the last action.
+     * @param action The action to add.
+     */
     addAction(action: IPaginatedMessageAction): this;
+    /**
+     * Clears all current pages and messages and sets them. The order given is the order they will be used.
+     * @param pages The pages to set.
+     */
     setPages(pages: MessagePage[]): this;
+    /**
+     * Add pages to the existing ones. The order given is the order they will be used.
+     * @param pages The pages to add.
+     */
     addPages(pages: MessagePage[]): this;
+    /**
+     * Adds a page to the existing ones. This will be added as the last page.
+     * @param page The page to add.
+     */
     addPage(page: MessagePage): this;
+    /**
+     * This executes the [[PaginatedMessage]] and sends the pages corresponding with [[PaginatedMessage.index]].
+     * The handler will start collecting reactions and running actions once all actions have been reacted to the message.
+     * @param author The author to validate.
+     * @param channel The channel to use.
+     */
     run(author: User, channel: TextChannel | NewsChannel): Promise<this>;
+    /**
+     * This function is executed on [[PaginatedMessage.run]]. This is an extendable method.
+     */
     resolvePagesOnRun(): Promise<void>;
+    /**
+     * This function is executed whenever an action is triggered and resolved.
+     * @param index The index to resolve.
+     */
     resolvePage(index?: number): Promise<APIMessage | null>;
+    /**
+     * This clones the current handler into a new instance.
+     */
     clone(): PaginatedMessage;
+    /**
+     * The default actions of this handler.
+     */
     static defaultActions: IPaginatedMessageAction[];
 }
+/**
+ * @example
+ * ```typescript
+ * // To utilize actions you can use the [[IPaginatedMessageAction]] by implementing it into a class.
+ *
+ * class ForwardAction implements IPaginatedMessageAction {
+ *   public id = '▶️';
+ *
+ *   public run({ handler }) {
+ *     if (handler.index !== handler.pages.length - 1) ++handler.index;
+ *   }
+ * }
+ *
+ * // You can also give the object directly.
+ *
+ * const StopAction: IPaginatedMessageAction {
+ *   id: '⏹️',
+ *   disableResponseEdit: true,
+ *   run: ({ response, collector }) => {
+ *     await response!.reactions.removeAll();
+ *     collector!.stop();
+ *   }
+ * }```
+ */
 export interface IPaginatedMessageAction {
@@ -27,2 +161,5 @@ id: string;
 }
+/**
+ * The context to be used in [[IPaginatedMessageAction]].
+ */
 export interface PaginatedMessageActionContext {
@@ -39,2 +176,24 @@ handler: PaginatedMessage;
 }
+/**
+ * The pages that are used for [[PaginatedMessage.pages]]
+ *
+ * Pages can be either an {@link https://discord.js.org/#/docs/main/stable/class/APIMessage APIMessage} directly,
+ * or an awaited function which returns an {@link https://discord.js.org/#/docs/main/stable/class/APIMessage APIMessage}.
+ *
+ * @example
+ * ```typescript
+ * // Direct usage as an APIMessage
+ *
+ * new APIMessage(message.channel, {
+ *   context: 'Test content!',
+ * });
+ *
+ * // An awaited function. This function also passes index, pages, and handler.
+ *
+ * (index, pages) =>
+ *   new APIMessage(message.channel, {
+ *     embed: new MessageEmbed().setFooter(`Page ${index + 1} / ${pages.length}`)
+ *   });
+ * ```
+ */
 export declare type MessagePage = ((index: number, pages: MessagePage[], handler: PaginatedMessage) => Awaited<APIMessage>) | APIMessage;
@@ -41,0 +200,0 @@ declare type Awaited<T> = PromiseLike<T> | T;

package.json

 {
 	"name": "@sapphire/discord.js-utilities",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"description": "Discord.js specific utilities for your JavaScript/TypeScript bots",
@@ -57,3 +57,3 @@ "author": "@sapphire",
 	},
-	"gitHead": "d4e15bc6ab9c21bef6a0fc67492ffd262291d4fc"
+	"gitHead": "66eb3d8cd6b0a07639e72d97b9b5698ce51a6320"
 }

No alert changes

Improved metrics

Total package byte prevSize

72395

increased by33.51%

Lines of code

295

increased by134.13%

No dependency changes