@open-discord-bots/framework 0.3.3 → 0.3.4

package/dist/api/modules/state.d.ts

@@ -0,0 +1,126 @@
+import { ODManager, ODValidId, ODManagerData, ODNoGeneric } from "./base.js";
+import { ODClientManager } from "./client.js";
+import { ODDebugger } from "./console.js";
+import { ODDatabase, ODDatabaseIdConstraint } from "./database.js";
+import * as discord from "discord.js";
+/**## ODStateKey `type`
+ * The key template for message states.
+ */
+export interface ODStateKey {
+    /**A valid discord server/guild ID or instance. */
+    guild?: discord.Guild | string | null;
+    /**A valid discord channel ID or instance. */
+    channel: discord.Channel | string;
+    /**A valid discord message ID or instance. */
+    message: discord.Message | string;
+    /**A valid discord user ID or instance. */
+    user?: discord.User | discord.GuildMember | string | null;
+}
+/**## ODStateData `type`
+ * The raw data template for message states used for storing in the database.
+ */
+export interface ODStateData<StateData extends any> {
+    /**The linked Guild ID of this message state. */
+    guildId: string | null;
+    /**The linked Channel ID of this message state. */
+    channelId: string;
+    /**The linked Message ID of this message state. */
+    messageId: string;
+    /**The linked User ID of this message state. */
+    userId: string | null;
+    /**The creation date of this state (UNIX TIMESTAMP). */
+    createdDate: number;
+    /**The modified date of this state (UNIX TIMESTAMP). */
+    modifiedDate: number;
+    /**Optional date after which this state should be regarded as expired (UNIX TIMESTAMP). */
+    deleteAfterDate: number | null;
+    /**The state data. */
+    data: StateData;
+}
+/**## ODStateSettings `type`
+ * Configurable settings for an ODState.
+ */
+export interface ODStateSettings {
+    /**(Default: `false`) Completely disable autodelete of message states. (unless manually activated using other settings) */
+    disableAutodelete: boolean;
+    /**(Default: `true`) Delete state on channel deletion. */
+    autodeleteOnChannelDelete: boolean;
+    /**(Default: `true`) Delete state on message deletion. */
+    autodeleteOnMessageDelete: boolean;
+    /**(Default: `true`) Delete state when the user leaves the guild/server. */
+    autodeleteOnUserLeave: boolean;
+    /**(Default: `false`) Delete state on bot restart. */
+    autodeleteOnRestart: boolean;
+    /**(Default: `true`) Delete state after 1 hour of an ephemeral message being sent. */
+    autodeleteOnEphemeral: boolean;
+    /**(Default: `null`) Delete state when unmodified/inactive for more than.... */
+    autodeleteAfterTimeout: null | {
+        time: number;
+        unit: "seconds" | "minutes" | "hours" | "days";
+    };
+}
+/**## ODState `class`
+ * An Open Discord state is a system for storing additional chunks of metadata for Discord messages.
+ * A system for tracking messages or linking metadata, states or progress to Discord messages (ID-based).
+ *
+ * Features automatic garbage collection to clear expired states.
+ */
+export declare class ODState<StateData extends any> extends ODManagerData {
+    /**Alias to Open Discord message states database. */
+    protected database: ODDatabase<ODDatabaseIdConstraint>;
+    /**Alias to Open Discord client manager. */
+    protected client: ODClientManager;
+    /**Alias to Open Discord debugger. */
+    protected debug: ODDebugger | null;
+    /**The settings of this state. */
+    settings: ODStateSettings;
+    constructor(id: ODValidId, client: ODClientManager, database: ODDatabase<ODDatabaseIdConstraint>, settings: Partial<ODStateSettings>);
+    /**Use the Open Discord debugger in this manager for logs. */
+    useDebug(debug?: ODDebugger | null): void;
+    /**Init the state and start autodeleting. The client must already be logged-in for this to work. */
+    init(): Promise<void>;
+    /**Purge all expired message states that reached a timeout or ephemeral. */
+    protected purgeExpiredStates(): Promise<void>;
+    /**Transform the object-based message state key contents to a string. */
+    protected transformKey(key: ODStateKey): string;
+    /**Transform the message state data contents for storage in the database. */
+    protected transformData(key: ODStateKey, data: StateData, isEphemeral: boolean, keepCreatedDate?: number): ODStateData<StateData>;
+    /**Calculate milliseconds from a time + unit. */
+    protected timeoutToUnixTime(): number | null;
+    /**Set a message state using guild, channel & message id as key. Returns `true` when overwritten. */
+    setMsgState(key: ODStateKey, data: StateData, isEphemeral: boolean): Promise<boolean>;
+    /**Get a message state using guild, channel & message id as key. */
+    getMsgState(key: ODStateKey): Promise<ODStateData<StateData> | null>;
+    /**Delete a message state using guild, channel & message id as key. Returns `true` when deleted. */
+    deleteMsgState(key: ODStateKey): Promise<boolean>;
+    /**List all message states of this `ODState`. */
+    listMsgStates(): Promise<{
+        key: string;
+        value: ODStateData<StateData>;
+    }[]>;
+    /**Delete all message states from this ODState. */
+    clearAllMsgStates(): Promise<void>;
+    /**Delete a message state using the raw key. Returns `true` when deleted. */
+    protected deleteMsgStateWithRawKey(rawKey: string): Promise<boolean>;
+}
+/**## ODStateManagerIdConstraint `type`
+ * The constraint/layout for id mappings/interfaces of the `ODStateManager` class.
+ */
+export type ODStateManagerIdConstraint = Record<string, ODState<any>>;
+/**## ODStateManager `class`
+ * The Open Discord state manager is a system for tracking messages or linking metadata, states or progress to Discord messages (ID-based).
+ *
+ * Features automatic garbage collection to clear expired states.
+ */
+export declare class ODStateManager<IdList extends ODStateManagerIdConstraint = ODStateManagerIdConstraint> extends ODManager<ODState<any>> {
+    constructor(debug: ODDebugger);
+    /**Init all states. */
+    init(): Promise<void>;
+    add(data: ODState<any>, overwrite?: boolean): boolean;
+    get<StateId extends keyof ODNoGeneric<IdList>>(id: StateId): IdList[StateId];
+    get(id: ODValidId): ODState<any> | null;
+    remove<StateId extends keyof ODNoGeneric<IdList>>(id: StateId): IdList[StateId];
+    remove(id: ODValidId): ODState<any> | null;
+    exists(id: keyof ODNoGeneric<IdList>): boolean;
+    exists(id: ODValidId): boolean;
+}

package/dist/api/modules/state.js

@@ -0,0 +1,222 @@
+///////////////////////////////////////
+//STATE MODULE
+///////////////////////////////////////
+import { ODManager, ODSystemError, ODManagerData } from "./base.js";
+/**## ODState `class`
+ * An Open Discord state is a system for storing additional chunks of metadata for Discord messages.
+ * A system for tracking messages or linking metadata, states or progress to Discord messages (ID-based).
+ *
+ * Features automatic garbage collection to clear expired states.
+ */
+export class ODState extends ODManagerData {
+    /**Alias to Open Discord message states database. */
+    database;
+    /**Alias to Open Discord client manager. */
+    client;
+    /**Alias to Open Discord debugger. */
+    debug = null;
+    /**The settings of this state. */
+    settings;
+    constructor(id, client, database, settings) {
+        super(id);
+        this.client = client;
+        this.database = database;
+        this.settings = {
+            disableAutodelete: false,
+            autodeleteOnChannelDelete: true,
+            autodeleteOnMessageDelete: true,
+            autodeleteOnUserLeave: true,
+            autodeleteOnRestart: false,
+            autodeleteOnEphemeral: true,
+            autodeleteAfterTimeout: null,
+            ...settings
+        };
+    }
+    /**Use the Open Discord debugger in this manager for logs. */
+    useDebug(debug) {
+        this.debug = debug ?? null;
+    }
+    /**Init the state and start autodeleting. The client must already be logged-in for this to work. */
+    async init() {
+        if (!this.client.loggedIn)
+            throw new ODSystemError("ODState('" + this.id.value + "').init() => The client must be logged in for states to initialize.");
+        //autodelete on restart
+        if (!this.settings.disableAutodelete && this.settings.autodeleteOnRestart)
+            this.clearAllMsgStates();
+        //autodelete on channelDelete
+        this.client.client.on("channelDelete", async (deletedChannel) => {
+            if (this.settings.disableAutodelete || !this.settings.autodeleteOnChannelDelete)
+                return;
+            for (const { key, value } of await this.listMsgStates()) {
+                if (value.channelId === deletedChannel.id)
+                    await this.deleteMsgStateWithRawKey(key);
+            }
+        });
+        //autodelete on messageDelete
+        this.client.client.on("messageDelete", async (deletedMsg) => {
+            if (this.settings.disableAutodelete || !this.settings.autodeleteOnMessageDelete)
+                return;
+            for (const { key, value } of await this.listMsgStates()) {
+                if (value.messageId === deletedMsg.id)
+                    await this.deleteMsgStateWithRawKey(key);
+            }
+        });
+        //autodelete on userLeave
+        this.client.client.on("guildMemberRemove", async (member) => {
+            if (this.settings.disableAutodelete || !this.settings.autodeleteOnUserLeave)
+                return;
+            if (member.guild.id !== this.client.mainServer?.id)
+                return;
+            for (const { key, value } of await this.listMsgStates()) {
+                if (value.userId === member.id)
+                    await this.deleteMsgStateWithRawKey(key);
+            }
+        });
+        //autodelete when expired (ephemeral/timeout) every 30 seconds
+        this.purgeExpiredStates();
+        setInterval(() => {
+            this.purgeExpiredStates();
+        }, 30 * 1000);
+        //create a list of all channels, messages & users that still exist (and are part of states)
+        const existingChannelIds = [];
+        const existingMessageIds = [];
+        const existingUserIds = [];
+        for (const { key, value } of await this.listMsgStates()) {
+            if (!existingChannelIds.includes(value.channelId)) {
+                //check if channel still exists
+                const channel = await this.client.fetchChannel(value.channelId);
+                if (channel)
+                    existingChannelIds.push(channel.id);
+            }
+            if (!existingMessageIds.includes(value.messageId)) {
+                //check if message still exists
+                const message = await this.client.fetchChannelMessage(value.channelId, value.messageId);
+                if (message)
+                    existingMessageIds.push(message.id);
+            }
+            if (value.userId && this.client.mainServer && !existingUserIds.includes(value.userId)) {
+                //check if user still exists
+                const user = await this.client.fetchGuildMember(this.client.mainServer.id, value.userId);
+                if (user)
+                    existingUserIds.push(user.id);
+            }
+        }
+        //delete all states where a channel, message or user is missing (when the bot was offline)
+        for (const { key, value } of await this.listMsgStates()) {
+            if (value.channelId && !existingChannelIds.includes(value.channelId))
+                await this.deleteMsgStateWithRawKey(key);
+            if (value.messageId && !existingMessageIds.includes(value.messageId))
+                await this.deleteMsgStateWithRawKey(key);
+            if (value.userId && !existingUserIds.includes(value.userId))
+                await this.deleteMsgStateWithRawKey(key);
+        }
+    }
+    /**Purge all expired message states that reached a timeout or ephemeral. */
+    async purgeExpiredStates() {
+        for (const { key, value } of await this.listMsgStates()) {
+            if (value.deleteAfterDate && value.deleteAfterDate < Date.now())
+                await this.deleteMsgStateWithRawKey(key);
+        }
+    }
+    /**Transform the object-based message state key contents to a string. */
+    transformKey(key) {
+        const newGuild = (!key.guild) ? "NULL" : (typeof key.guild === "string" ? key.guild : key.guild.id);
+        const newChannel = (!key.channel) ? "NULL" : (typeof key.channel === "string" ? key.channel : key.channel.id);
+        const newMessage = (!key.message) ? "NULL" : (typeof key.message === "string" ? key.message : key.message.id);
+        const newUser = (!key.user) ? "NULL" : (typeof key.user === "string" ? key.user : key.user.id);
+        return `G:${newGuild},C:${newChannel},M:${newMessage},U:${newUser}`;
+    }
+    /**Transform the message state data contents for storage in the database. */
+    transformData(key, data, isEphemeral, keepCreatedDate) {
+        const guildId = (!key.guild) ? null : (typeof key.guild === "string" ? key.guild : key.guild.id);
+        const channelId = (typeof key.channel === "string" ? key.channel : key.channel.id);
+        const messageId = (typeof key.message === "string" ? key.message : key.message.id);
+        const userId = (!key.user) ? null : (typeof key.user === "string" ? key.user : key.user.id);
+        const createdDate = keepCreatedDate ?? Date.now();
+        const modifiedDate = Date.now();
+        const unmodifiedTimeoutDate = this.timeoutToUnixTime();
+        const ephemeralTimeoutDate = (isEphemeral) ? Date.now() + (3600 * 1000) : null; //delete ephemeral state after 1 hour
+        const deleteAfterDate = (unmodifiedTimeoutDate) ? unmodifiedTimeoutDate : ephemeralTimeoutDate;
+        return { guildId, channelId, messageId, userId, createdDate, modifiedDate, deleteAfterDate, data };
+    }
+    /**Calculate milliseconds from a time + unit. */
+    timeoutToUnixTime() {
+        const timeout = this.settings.autodeleteAfterTimeout;
+        if (!timeout)
+            return null;
+        if (timeout.unit == "seconds")
+            return Date.now() + (timeout.time * 1000);
+        else if (timeout.unit == "minutes")
+            return Date.now() + (timeout.time * 1000 * 60);
+        else if (timeout.unit == "hours")
+            return Date.now() + (timeout.time * 1000 * 3600);
+        else if (timeout.unit == "days")
+            return Date.now() + (timeout.time * 1000 * 3600 * 24);
+        else
+            return null;
+    }
+    /**Set a message state using guild, channel & message id as key. Returns `true` when overwritten. */
+    async setMsgState(key, data, isEphemeral) {
+        const rawKey = this.transformKey(key);
+        const existingData = await this.getMsgState(key);
+        const contents = this.transformData(key, data, isEphemeral, existingData?.createdDate);
+        return await this.database.set(this.id.value, rawKey, contents);
+    }
+    /**Get a message state using guild, channel & message id as key. */
+    async getMsgState(key) {
+        const rawKey = this.transformKey(key);
+        const rawData = await this.database.get(this.id.value, rawKey);
+        if (typeof rawData !== "object")
+            return null;
+        else
+            return rawData;
+    }
+    /**Delete a message state using guild, channel & message id as key. Returns `true` when deleted. */
+    async deleteMsgState(key) {
+        const rawKey = this.transformKey(key);
+        return await this.database.delete(this.id.value, rawKey);
+    }
+    /**List all message states of this `ODState`. */
+    async listMsgStates() {
+        return ((await this.database.getCategory(this.id.value)) ?? []);
+    }
+    /**Delete all message states from this ODState. */
+    async clearAllMsgStates() {
+        for (const state of await this.database.getAll()) {
+            await this.database.delete(state.category, state.key);
+        }
+    }
+    /**Delete a message state using the raw key. Returns `true` when deleted. */
+    async deleteMsgStateWithRawKey(rawKey) {
+        return await this.database.delete(this.id.value, rawKey);
+    }
+}
+/**## ODStateManager `class`
+ * The Open Discord state manager is a system for tracking messages or linking metadata, states or progress to Discord messages (ID-based).
+ *
+ * Features automatic garbage collection to clear expired states.
+ */
+export class ODStateManager extends ODManager {
+    constructor(debug) {
+        super(debug, "state");
+    }
+    /**Init all states. */
+    async init() {
+        for (const state of this.getAll()) {
+            await state.init();
+        }
+    }
+    add(data, overwrite) {
+        data.useDebug(this.debug);
+        return super.add(data, overwrite);
+    }
+    get(id) {
+        return super.get(id);
+    }
+    remove(id) {
+        return super.remove(id);
+    }
+    exists(id) {
+        return super.exists(id);
+    }
+}

package/dist/startup/errorHandling.js

@@ -1,5 +1,7 @@
 import * as api from "../api/index.js";
 export function loadErrorHandling(opendiscord, project) {
+    //increase error stack trace
+    Error.stackTraceLimit = 50;
     process.on("uncaughtException", async (error, origin) => {
         try {
             const beforeEvent = opendiscord.events.get("onErrorHandling");

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@open-discord-bots/framework",
     "author": "DJj123dj",
-    "version": "0.3.3",
+    "version": "0.3.4",
     "description": "The core framework of the popular open-source discord bots: Open Ticket & Open Moderation.",
     "main": "dist/index.js",
     "module": "dist/index.js",

package/src/api/index.ts

@@ -25,6 +25,7 @@ export * from "./modules/progressbar.js"
 export * from "./modules/responder.js"
 export * from "./modules/session.js"
 export * from "./modules/startscreen.js"
+export * from "./modules/state.js"
 export * from "./modules/statistic.js"
 export * from "./modules/verifybar.js"
 export * from "./modules/worker.js"

package/src/api/main.ts

@@ -24,6 +24,7 @@ import { ODClientManager } from "./modules/client.js"
 import { ODSharedFuseManager } from "./modules/fuse.js"
 import { ODStartScreenManager } from "./modules/startscreen.js"
 import { ODComponentManager } from "./modules/component.js"
+import { ODStateManager } from "./modules/state.js"
 
 /**## ODMainManagers `interface`
  * The global properties for the main class of the bot.
@@ -89,6 +90,8 @@ export interface ODMainManagers {
     code: ODCodeManager
     /**A collection of static Discord post channels. It allows the bot to find back log, transcript or configured channels based on a linked ID. */
     posts: ODPostManager
+    /**A system for tracking messages or linking metadata, states or progress to Discord messages (ID-based). Features automatic garbage collection. */
+    states: ODStateManager
     
     /**A wrapper around the `discord.Client` class. It handles client login, activity and registering text/slash commands. */
     client: ODClientManager
@@ -140,6 +143,7 @@ export abstract class ODMain implements ODMainManagers {
     readonly statistics: ODStatisticManager
     readonly code: ODCodeManager
     readonly posts: ODPostManager
+    readonly states: ODStateManager
     
     readonly client: ODClientManager
     readonly sharedFuses: ODSharedFuseManager
@@ -150,7 +154,7 @@ export abstract class ODMain implements ODMainManagers {
     constructor(managers:ODMainManagers,project:ODProjectType){
         this.project = project
         this.versions = managers.versions
-        this.versions.add(ODVersion.fromString("opendiscord:api","v0.3.3"))
+        this.versions.add(ODVersion.fromString("opendiscord:api","v0.3.4"))
         this.versions.add(ODVersion.fromString("opendiscord:livestatus","v2.0.0"))
 
         this.debugfile = managers.debugfile
@@ -179,6 +183,7 @@ export abstract class ODMain implements ODMainManagers {
         this.statistics = managers.statistics
         this.code = managers.code
         this.posts = managers.posts
+        this.states = managers.states
         
         this.sharedFuses = managers.sharedFuses
         this.env = managers.env