@somehiddenkey/discord-command-utils 2.0.1 → 2.1.1

package/README.md

@@ -62,10 +62,48 @@ Your local configuration JSON file should look like this:
 ### Global configuration
 Loads the global configuration that contains information related to all bot instances, like snowflake IDs of channels, categories, guild, etc. Load a new instance of your global config through the following code:
 ```js
-export const globalConfig = GlobalConfig.load("../global_config.json");
+export const globalConfig = GlobalConfig.load("../global_config.json", bot);
 ```
 It contains the IDs of the following sections: guilds, categories, channels, log channels and roles. These can be used as constant values throughout your code, making sure that if an ID ever changes, that all bot instances would take the new updated value by simply updating the json once.
 
+#### Properties
+The properties of the different guilds can read per scope/guild. We differentiate the main, tutor, staff and community server:
+- Get the ID of the main server : `globalConfig.main.guild.id`
+- Get the ID of the general chat in the main server: `globalConfig.main.channels.international.id`
+
+#### Caching
+You can fetch and cache the value of a guild, channel or role from discordjs, as to access it immidiately afterwards. However, at all times, the id is available even without fetching
+```js
+console.write(globalConfig.main.guild.name); //error: not fetched yet
+console.write(globalConfig.main.guild.id); 	//still fine, ID always accessible
+
+await globalConfig.main.guild.fetch();
+await globalConfig.main.channels.international.fetch();
+console.write(globalConfig.main.guild.name); //uses the cached value
+```
+
+Please keep in mind that cached value may contain outdated data! If you call `fetch()` it will either return the cached value or fetch the value once. If you want to reload the value e.g. to read the updated members that are in a specific voicechannel, you must call `refresh()`
+
+```js
+console.write(globalConfig.main.channels.break_afk.members.length); 
+//shows the member count at the time of the fetch()
+
+await globalConfig.main.channels.break_afk.refresh();
+//fetches the value again, and caches it again
+
+console.write(globalConfig.main.channels.break_afk.members.length); 
+//shows the now updated member count
+```
+
+You can fetch and refresh entire groups or guilds. Please keep in mind that, if you fetch the values of a specific guild, the bot has to actually be part of that server. A value that cannot be fetched will result in an error.
+
+```js
+await globalConfig.community.fetch();
+await globalConfig.main.channels.fetch();
+
+console.write(globalConfig.main.channel.international.name); //uses the cached value
+```
+
 ### Secrets configuration
 Loads the environment variables that contain all secrets for that bot, like your bot token and database credentials. It goes without saying that these actual values may never be git traced. Load new instance of your secret config through the following code: 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somehiddenkey/discord-command-utils",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "A utility library for building Discord bot commands using discord.js",
   "author": {
     "email": "k3y.throwaway@gmail.com",

package/src/Configs/Fetchable.js

@@ -25,6 +25,13 @@ export default class Fetchable {
                     if (prop === "id") 
                         return id;
 
+                    if (prop === "refresh") {
+                        return async () => {
+                            cachedObject = await fetcher(id);
+                            return cachedObject;
+                        };
+                    }
+
                     if (prop === "fetch") {
                         return async () => {
                             if (!cachedObject){
@@ -66,4 +73,13 @@ export default class Fetchable {
             this._config_keys.map((key) => this[key]?.fetch())
         );
     }
+
+    /**
+     * @returns {Promise<void[]>} 
+     */
+    refresh() {
+        return Promise.all(
+            this._config_keys.map((key) => this[key]?.refresh())
+        );
+    }
 }

package/src/Configs/GlobalConfig/GlobalConfig.js

@@ -10,21 +10,22 @@ import {default as GuildCommunity} from './GlobalConfigCommunity.js';
 import {default as GuildTutor} from './GlobalConfigTutor.js';
 import {default as GuildStaff} from './GlobalConfigStaff.js';
 import { GuildBased } from '../NestedGlobalConfig.js';
+import { Client } from 'discord.js';
 
 export default class GlobalConfig {
     main
     community
     tutor
     staff
-
+    
     /**
      * Loads the JSON file and returns a GlobalConfig instance.
      * @param {string} path
-     * @param {string} environment
+     * @param {Client} bot
      * @returns {GlobalConfig}
      */
-    static async load(path) {
-        var json
+    static async load(path, bot) {
+        var json;
         try {
             const raw = fs.readFileSync(path, { encoding: 'utf8', flag: 'r' });
             json = JSON.parse(raw);
@@ -32,7 +33,7 @@ export default class GlobalConfig {
             consola.error(`Failed to load GlobalConfig from path: ${path}`, error);
             throw error;
         }
-        return new GlobalConfig(json.guilds);
+        return new GlobalConfig(json.guilds, bot);
     }
 
         /**
@@ -73,11 +74,11 @@ export default class GlobalConfig {
         }
     }
 
-    constructor(data) {
-        this.main = new GuildMain(data.main);
-        this.community = new GuildCommunity(data.community);
-        this.tutor = new GuildTutor(data.tutor);
-        this.staff = new GuildStaff(data.staff);
+    constructor(data, bot) {
+        this.main = new GuildMain(data.main, bot);
+        this.community = new GuildCommunity(data.community, bot);
+        this.tutor = new GuildTutor(data.tutor, bot);
+        this.staff = new GuildStaff(data.staff, bot);
     }
 }
 

package/src/Configs/GlobalConfig/GlobalConfigMain.js

@@ -17,11 +17,11 @@ export default class Guild extends GuildBased {
     /** @type {Roles} */
     roles;
 
-    constructor(data) {
+    constructor(data, bot) {
         if (!data) 
             throw new ConfigError('No data initialized for GlobalConfig');
 
-        super(data);
+        super(data, bot);
         this.categories = new Categories(data.categories, this.guild);
         this.channels = new Channels(data.channels, this.guild);
         this.logs = new Logs(data.logs, this.guild);
@@ -65,8 +65,8 @@ class Categories extends ChannelBased {
     /** @type {Set<Snowflake>} */
     study_rooms;
 
-    constructor(data) {
-        super(data);
+    constructor(data, guild) {
+        super(data, guild);
         this.custom_study_rooms = new Set(data.custom_rooms.concat(data.verified_com));
         this.study_rooms = new Set([...this.custom_study_rooms, data.music, data.timer_25, data.timer_50, data.screen_cam]);
     }
@@ -166,8 +166,8 @@ class Roles extends RoleBased {
     all_staff;
 
 
-    constructor(data) {
-        Object.assign(this, data);
+    constructor(data, guild) {        
+        super(data, guild);
         this.all_staff = [this.jr_staff, this.sr_staff, this.st_team, this.coordinator];
     }
 }

package/src/Configs/GlobalConfig/GlobalConfigStaff.js

@@ -17,11 +17,11 @@ export default class Guild extends GuildBased {
     /** @type {Roles} */
     roles;
 
-    constructor(data) {
+    constructor(data, bot) {
         if (!data) 
             throw new ConfigError('No data initialized for GlobalConfig');
 
-        super(data);
+        super(data, bot);
         this.categories = new Categories(data.categories, data.id);
         this.channels = new Channels(data.channels, data.id);
         this.logs = new Logs(data.logs, data.id);

package/src/Configs/GlobalConfig/GlobalConfigTutor.js

@@ -17,11 +17,11 @@ export default class Guild extends GuildBased {
     /** @type {Roles} */
     roles;
 
-    constructor(data) {
+    constructor(data, bot) {
         if (!data) 
             throw new ConfigError('No data initialized for GlobalConfig');
 
-        super(data);
+        super(data, bot);
         this.categories = new Categories(data.categories, data.id);
         this.channels = new Channels(data.channels, data.id);
         this.logs = new Logs(data.logs, data.id);

package/src/Configs/NestedGlobalConfig.js

@@ -17,12 +17,12 @@ export class GuildBased extends Fetchable {
      * @param {Snowflake} id 
      * @returns {Proxy}
      */
-    _createLazyObject(id) {
+    _createLazyObject(id, bot) {
         return super._createLazyObject(id, async (id) => await bot.guilds.fetch(id));
     }
 
-    constructor(data){
-        this.guild = this._createLazyObject(data.id);
+    constructor(data, bot) {
+        this.guild = this._createLazyObject(data.id, bot);
         this._config_keys = Object.keys(data).filter(k => k !== 'id').push('guild');
     }
 }
@@ -49,7 +49,7 @@ export class RoleBased extends Fetchable {
     /** @type {Guild} */
     #guild;
 
-    constructor(data) {
+    constructor(data, guild) {
         this.#guild = guild;
         super(data);
     }