feat: v1.1.0

.editorconfig

@@ -1,5 +1,6 @@
 root = true
 
+
 [*]
 indent_style = space
 indent_size = 4

.eslintrc.js

@@ -81,7 +81,13 @@ module.exports = {
             'interface'
         ],
 
-        '@typescript-eslint/no-unused-vars': 'warn',
+        '@typescript-eslint/no-unused-vars': [
+            'warn',
+            {
+                varsIgnorePattern: '^_'
+            }
+        ],
+
         '@typescript-eslint/explicit-function-return-type': 'warn',
 
         '@typescript-eslint/explicit-module-boundary-types': 'off',

.gitignore

@@ -19,5 +19,6 @@ data/
 # vim swap files
 *.sw[nop]
 
-# test scripts
+# test scripts & data
 test/
+test123.json

.husky/pre-commit

@@ -6,7 +6,7 @@ cleanup() {
     rm -rf types
 }
 
-cleanup && npm run build
-# bash scripts/minify.sh
+cleanup
 
+npm run build
 git add .

.npmignore

@@ -25,8 +25,9 @@ scripts/
 # documentation
 docs/
 
-# testing files
+# testing files & data
 test/
+test123.json
 
 # backup files
 *.bak

README.md

@@ -16,7 +16,7 @@
 - Database Caching System 📚
 - Easy to Understand 👍
 - Beginner Friendly 😄
-- Extremely Fast 💨
+- High Performance 💨
 
 ## 📂 | Installation
 **Node.js v16.9.0 or newer is required to install.**
@@ -44,7 +44,7 @@ $ pnpm add discord-giveaways-super
 ## ❗ | Useful Links
 - [Documentation](https://dgs-docs.js.org)
 - [NPM](https://www.npmjs.com/package/discord-giveaways-super)
-- [Frequently Asked Questions](https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq)
+- [Frequently Asked Questions](https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq)
 - [GitHub](https://github.com/shadowplay1/discord-giveaways-super)
 - [Examples](https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples)
 - [Discord Server](https://discord.gg/4pWKq8vUnb)

docs/general/changelog.md

@@ -9,10 +9,62 @@
 ## ⏰ | Changelog
 
 **v1.1.0**:
-- Fixed Discord ID typings bug in `Giveaways.start()` method.
-- Added giveaways participants filters object in `Giveaways.start()` method - now you can restrict members from participating in a giveaway if they don't have any of the required roles or have any of the forbidden roles.
-- Updated `discord.js` to the latest stable version.
-- Minor bugfixes.
+- Fixed `DiscordID` types bug in `Giveaways.start()` method.
+- Fixed the incorrect giveaway end timestamp being assigned on giveaway start.
+- Fixed inconsistencies after the giveaway being deleted.
+- Improved the time strings validation.
+- Improved internal types.
+- Added the `Giveaway.winners` property that saves an array of user IDs who won the giveaway.
+- Added giveaways participants filters object in `Giveaways.start()` method - now you can **restrict** members from participating in a giveaway if they don't have any of the **required** roles or if they have any of the **forbidden** roles, or you can now restrict the **members** themselves from joining your giveaway!
+- - Added a `participantsFilter` object in `Giveaway.start()` configuration;
+- - Added the `restrictionsMessages` embed strings definition callback so you could define the messages that are being sent in various join rejection cases! 
+
+Here's how you can use this new feature:
+
+```ts
+const newGiveaway = await giveaways.start({
+    // ... (other giveaway settings)
+
+    // example usage of participants filtering (only IDs are supported)
+    participantsFilter: {
+        requiredRoles: ['<@&841642867100221452>', '<@&669259475156205583>', '841642867100221452', '669259475156205583'],
+        restrictedRoles: ['<@&692002313187098677>', '<@&765209398318465075>', '692002313187098677', '765209398318465075'],
+        restrictedMembers: ['<@1121494265164468376>', '1121494265164468376']
+    },
+
+    defineEmbedStrings(giveaway, host, participantsFilters) {
+        return {
+            // ... (other strings definitions)
+
+            restrictionsMessages(memberMention) {
+                return {
+                    hasNoRequiredRoles: {
+                        messageContent: `:x: | ${memberMention}, you **must** have at least one of the following roles ` +
+                            `to join this giveaway: ${participantsFilters.requiredRoles?.join(', ')}`
+                    },
+
+                    hasRestrictedRoles: {
+                        messageContent: `:x: | ${memberMention}, you **cannot** have any of the following roles ` +
+                            `to join this giveaway: ${participantsFilters.restrictedRoles?.join(', ')}`
+                    },
+
+                    memberRestricted: {
+                        messageContent: `:x: | ${memberMention}, you're **not allowed** to join this giveaway.`
+                    }
+                }
+            }
+
+            // ... (other strings definitions)
+        }
+    }
+})
+```
+
+- Bumped `discord.js` to the latest stable version.
+- Renamed the `Giveaway.entriesArray` property to `Giveaway.entries`. Please note that this is **not** the type of `Object.entries()` method, but a property that shows all the users who joined the giveaway.
+- Improved **[Frequently Asked Questions](https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq)** page and added more useful and frequently asked questions about the module.
+- Fixed some documentation typos and mismatches.
+- Made some minor bugfixes, types improvements & JSDoc improvements.
 
 **v1.0.5**:
 - Renamed the `checkingCountdown` option from JSON configuration options to `checkingInterval` so it would make more sense.
@@ -39,7 +91,7 @@
 ## ❗ | Useful Links
 <ul>
 <li><b><a href = "https://www.npmjs.com/package/discord-giveaways-super">NPM</a></b></li>
-<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq">Frequently Asked Questions</a></b></li>
+<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq">Frequently Asked Questions</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super">GitHub</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples">Examples</a></b></li>
 <li><b><a href = "https://discord.gg/4pWKq8vUnb">Discord Server</a></b></li>

docs/general/configuring.md

@@ -14,7 +14,7 @@ You know that the module has a lot of different settings and you can set them up
 
 The module has support for **3** types of databases: **__JSON__**, **__MongoDB__** and **__Enmap__**.
 
-To set up the database to work in Discord Giveaways Super, we need to specify 2 important configuration properties: [`database`](https://dgs-docs.js.org/#/docs/main/1.0.5/typedef/IGiveawaysConfiguration%3CTDatabaseType%3E) and [`connection`](https://dgs-docs.js.org/#/docs/main/1.0.5/typedef/IGiveawaysConfiguration%3CTDatabaseType%3E)
+To set up the database to work in Discord Giveaways Super, we need to specify 2 important configuration properties: [`database`](https://dgs-docs.js.org/#/docs/main/1.1.0/typedef/IGiveawaysConfiguration%3CTDatabaseType%3E) and [`connection`](https://dgs-docs.js.org/#/docs/main/1.1.0/typedef/IGiveawaysConfiguration%3CTDatabaseType%3E)
 
 - `database` is the type of database we want to use
 - `connection` is the configuration for the database which we have chosen
@@ -265,7 +265,7 @@ const giveawaysConfigExample = {
 ## ❗ | Useful Links
 <ul>
 <li><b><a href = "https://www.npmjs.com/package/discord-giveaways-super">NPM</a></b></li>
-<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq">Frequently Asked Questions</a></b></li>
+<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq">Frequently Asked Questions</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super">GitHub</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples">Examples</a></b></li>
 <li><b><a href = "https://discord.gg/4pWKq8vUnb">Discord Server</a></b></li>

docs/general/embed-strings.md

@@ -43,7 +43,7 @@ To customize these messages, you can define different properties within the embe
 await giveaway.start({
 	// ... (other giveaway starting options)
 
-	defineEmbedStrings(giveaway, host) {
+	defineEmbedStrings(giveaway, host, participantsFilters) {
 	    return {
 	        joinGiveawayMessage: {
 	            messageContent: 'You have joined the giveaway!'
@@ -62,8 +62,10 @@ await giveaway.start({
 	            title: `Giveaway (ID: ${giveaway.id})`,
 	            titleIcon: client.user?.displayAvatarURL({ size: 2048 }),
 
-	            description: `Prize: **${giveaway.prize}**.\nWinners: **${giveaway.winnersCount}**\n` +
-	                `Entries: **${giveaway.entriesCount}**\nHost: **${host.username}**\nEnds at: <t:${giveaway.endTimestamp}:R>`,
+                description: `Prize: **${giveaway.prize}**.\nWinners: **${giveaway.winnersCount}**\n` +
+                    `Entries: **${giveaway.entriesCount}**\nHost: **${host.username}**\nEnds at: <t:${giveaway.endTimestamp}:R>\n\n` + 
+                    `- Required roles: ${participantsFilters.requiredRoles?.join(', ') || 'none'}\n` +
+                    `- Forbidden roles: ${participantsFilters.restrictedRoles?.join(', ') || 'none'}\n`,
 
 	            footer: `Ends at:`,
 	            timestamp: giveaway.endTimestamp,
@@ -76,7 +78,7 @@ await giveaway.start({
 	    finish(mentionsString, winnersCount) {
 	        return {
 	            endMessage: {
-	                messageContent: `Congratulations ${mentionsString} on winning!`
+	                messageContent: `Congratulations ${mentionsString} on winning **${giveaway.prize}**!`
 	            },
 	            // ... (other properties)
 	        }
@@ -136,7 +138,7 @@ await giveaway.start({
 ## ❗ | Useful Links
 <ul>
 <li><b><a href = "https://www.npmjs.com/package/discord-giveaways-super">NPM</a></b></li>
-<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq">Frequently Asked Questions</a></b></li>
+<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq">Frequently Asked Questions</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super">GitHub</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples">Examples</a></b></li>
 <li><b><a href = "https://discord.gg/4pWKq8vUnb">Discord Server</a></b></li>

docs/general/examples.md

@@ -33,7 +33,7 @@ const giveaways = new Giveaways(client, {
 
     connection: {
         // database configuration object,
-		// see https://dgs-docs.js.org/#/docs/main/1.0.5/general/configuring
+		// see https://dgs-docs.js.org/#/docs/main/1.1.0/general/configuring
 		// for more info
     }
 })
@@ -103,6 +103,13 @@ if (message.content.startsWith(prefix + 'giveaway-start')) {
         time,
         winnersCount,
 
+        // example usage of participants filtering (only IDs are supported)
+        participantsFilter: {
+            requiredRoles: ['<@&841642867100221452>', '<@&669259475156205583>', '841642867100221452', '669259475156205583'],
+            restrictedRoles: ['<@&692002313187098677>', '<@&765209398318465075>', '692002313187098677', '765209398318465075']
+            restrictedMembers: ['<@1121494265164468376>', '1121494265164468376']
+        },
+
         // defining *all* the messages for the giveaway
 
         // please note that all the properties
@@ -114,9 +121,9 @@ if (message.content.startsWith(prefix + 'giveaway-start')) {
         // of "defineEmbedStrings" function are also will be replaced with
         // placeholder values
 
-		// see https://dgs-docs.js.org/#/docs/main/1.0.5/general/embed-strings
+		// see https://dgs-docs.js.org/#/docs/main/1.1.0/general/embed-strings
 		// for more info about defining embeds
-		defineEmbedStrings(giveaway, host) {
+		defineEmbedStrings(giveaway, host, participantsFilters) {
     		return {
 
                 // this ephemeral reply will be sent when they join the giveaway (embeds may also be used here)
@@ -135,7 +142,10 @@ if (message.content.startsWith(prefix + 'giveaway-start')) {
         		start: {
             		messageContent: ':tada: **GIVEAWAY STARTED!** :tada:',
             		title: 'Giveaway Info',
-            		description: `Prize: ${giveaway.prize}\nWinners: ${giveaway.winnersCount}`,
+                    description: `Prize: **${giveaway.prize}**.\nWinners: **${giveaway.winnersCount}**\n` +
+                        `Entries: **${giveaway.entriesCount}**\nHost: **${host.username}**\nEnds at: <t:${giveaway.endTimestamp}:R>\n\n` + 
+                        `- Required roles: ${participantsFilters.requiredRoles?.join(', ') || 'none'}\n` +
+                        `- Forbidden roles: ${participantsFilters.restrictedRoles?.join(', ') || 'none'}\n`,
             		// ... (other properties)
         		},
 
@@ -147,7 +157,7 @@ if (message.content.startsWith(prefix + 'giveaway-start')) {
                         // this message will be sent separately in the giveaway channel when the giveaway ends
                         // used to mention the giveaway winners
                 		endMessage: {
-                    		messageContent: `Congratulations ${mentionsString} on winning!`
+                    		messageContent: `Congratulations ${mentionsString} on winning **${giveaway.prize}**!`
             				// ... (other properties)
                 		},
 
@@ -158,7 +168,7 @@ if (message.content.startsWith(prefix + 'giveaway-start')) {
 
                             title: `Giveaway (ID: ${giveaway.id})`,
                             description: `Prize: **${giveaway.prize}**\nEntries: **${giveaway.entriesCount}**\n` +
-                                `${giveaway.winnersCount == 1 ? 'Winner' : `Winners **(${winnersCount})**`}: ${mentionsString} `,
+                                `${winnersCount == 1 ? 'Winner' : `Winners **(${winnersCount})**`}: ${mentionsString} `,
 
                             footer: `Ended at:`,
                             timestamp: giveaway.endedTimestamp
@@ -215,7 +225,7 @@ if (message.content.startsWith(prefix + 'giveaway-start')) {
                         // this message will be sent separately in the giveaway channel after the reroll
                         // used to mention the new giveaway winners (embeds may also be used here)
                         rerollMessage: {
-                            messageContent: `${giveaway.winnersCount == 1 ? 'New winner is' : 'New winners are'} ` +
+                            messageContent: `${winnersCount == 1 ? 'New winner is' : 'New winners are'} ` +
                                 `${mentionsString}, congratulations!`
             				// ... (other properties)
                         },
@@ -613,7 +623,7 @@ View the **full bot examples** in both **JavaScript** and **TypeScript** [here](
 ## ❗ | Useful Links
 <ul>
 <li><b><a href = "https://www.npmjs.com/package/discord-giveaways-super">NPM</a></b></li>
-<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq">Frequently Asked Questions</a></b></li>
+<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq">Frequently Asked Questions</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super">GitHub</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples">Examples</a></b></li>
 <li><b><a href = "https://discord.gg/4pWKq8vUnb">Discord Server</a></b></li>

docs/general/faq.md

@@ -8,11 +8,65 @@
 
 ## ❓ | Frequently Asked Questions
 
+### **Q:** How do I add requirements to join the giveaway?
+### **A:** You can add up to **3** different types of join requirements for the giveaway:
+- Having one of the required roles (array of **role IDs**)
+- Not having any of the restricted roles (array of **role IDs**)
+- Restriction of selected users (array of **user IDs**)
+
+To add these restrictions, you will need to add the `participantsFilter` property inside your giveaway configuration in `Giveaways.start()` method. Here's how to do it:
+
+In the example below:
+- Setting up the **required roles** in `requiredRoles` setting in `participantsFilter` object in giveaway configuration.
+- Setting up the **restricted roles** in `restrictedRoles` setting in `participantsFilter` object in giveaway configuration.
+- Setting up the **restricted users** in `restrictedMembers` setting in `participantsFilter` object in giveaway configuration.
+
+```ts
+const myGiveaway = await giveaways.start({
+    channelID: channel.id,
+    guildID: message.guild.id,
+    hostMemberID: message.author.id,
+    prize: 'giveaway prize',
+    time: '1d',
+    winnersCount: 1,
+
+    // example usage of participants filtering (only IDs are supported)
+    participantsFilter: {
+        requiredRoles: ['<@&841642867100221452>', '<@&669259475156205583>', '841642867100221452', '669259475156205583'],
+        restrictedRoles: ['<@&692002313187098677>', '<@&765209398318465075>', '692002313187098677', '765209398318465075'],
+        restrictedMembers: ['<@1121494265164468376>', '1121494265164468376']
+    },
+
+    // other giveaway settings...
+})
+```
+
+### **Q:** How does this module work?
+### **A:** 
+- You setup the database details in `Giveaways` constructor:
+
+```ts
+const giveaways = new Giveaways(client, {
+    database: DatabaseType.JSON // either DatabaseType.JSON, DatabaseType.MONGODB or DatabaseType.ENMAP,
+
+    connection: {
+        // database configuration object,
+		// see https://dgs-docs.js.org/#/docs/main/1.1.0/general/configuring
+		// for more info
+    }
+})
+```
+
+- Then, when starting a giveaway, you configure all the giveaway settings, messages and strings;
+- The rest of the job will be done by the module!
+
 ### **Q:** Is there `EmbedBuilder` support to configure giveaway messages as embeds?
 ### **A:** Not at the moment, but this will added in the future!
 
 ### **Q:** Is there support for (X) database?
-### **A:** At the moment, there's only support for 3 databases: **JSON**, **MongoDB** and **Enmap**, but support for other databases may be added in the future as well!
+### **A:** At the moment, there's only support for 3 databases: **JSON**, **MongoDB** and **Enmap**, but support for other databases may be added in the future as well! 
+
+> Don't forget that all strings definitions settings are optional and they're being replaced with fallback values if omitted, no need to be scared of the big configuration :)
 
 ### **Q:** How do I disable the post-install console message?
 ### **A:** Head to your `package.json` and add the following property:
@@ -28,7 +82,7 @@ Got a question? Feel free to ask it in our [Support Server](https://discord.gg/4
 ## ❗ | Useful Links
 <ul>
 <li><b><a href = "https://www.npmjs.com/package/discord-giveaways-super">NPM</a></b></li>
-<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq">Frequently Asked Questions</a></b></li>
+<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq">Frequently Asked Questions</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super">GitHub</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples">Examples</a></b></li>
 <li><b><a href = "https://discord.gg/4pWKq8vUnb">Discord Server</a></b></li>

docs/general/welcome.md

@@ -34,7 +34,7 @@ Features:
 <li><b>Database Caching System 📚</b></li>
 <li><b>Easy to Understand 👍</b></li>
 <li><b>Beginner Friendly 😄</b></li>
-<li><b>Extremely Fast 💨</b></li>
+<li><b>High Performance 💨</b></li>
 
 </ul>
 
@@ -56,7 +56,7 @@ Features:
 ## ❗ | Useful Links
 <ul>
 <li><b><a href = "https://www.npmjs.com/package/discord-giveaways-super">NPM</a></b></li>
-<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.0.5/general/faq">Frequently Asked Questions</a></b></li>
+<li><b><a href = "https://dgs-docs.js.org/#/docs/main/1.1.0/general/faq">Frequently Asked Questions</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super">GitHub</a></b></li>
 <li><b><a href = "https://github.com/shadowplay1/discord-giveaways-super/tree/main/examples">Examples</a></b></li>
 <li><b><a href = "https://discord.gg/4pWKq8vUnb">Discord Server</a></b></li>