@open-discord-bots/framework 0.0.1 → 0.0.2

package/src/api/modules/cooldown.ts

@@ -0,0 +1,348 @@
+///////////////////////////////////////
+//COOLDOWN MODULE
+///////////////////////////////////////
+import { ODId, ODValidId, ODManager, ODSystemError, ODManagerData } from "./base"
+import { ODDebugger } from "./console"
+
+/**## ODCooldownManager `class`
+ * This is an Open Discord cooldown manager.
+ * 
+ * It is responsible for managing all cooldowns in Open Discord. An example of this is the ticket creation cooldown.
+ * 
+ * There are many types of cooldowns available, but you can also create your own!
+ */
+export class ODCooldownManager extends ODManager<ODCooldown<object>> {
+    constructor(debug:ODDebugger){
+        super(debug,"cooldown")
+    }
+    /**Initiate all cooldowns in this manager. */
+    async init(){
+        for (const cooldown of this.getAll()){
+            await cooldown.init()
+        }
+    }
+}
+
+/**## ODCooldownData `class`
+ * This is Open Discord cooldown data.
+ * 
+ * It contains the instance of an active cooldown (e.g. for a user). It is handled by the cooldown itself.
+ */
+export class ODCooldownData<Data extends object> extends ODManagerData {
+    /**Is this cooldown active? */
+    active: boolean
+    /**Additional data of this cooldown instance. (different for each cooldown type) */
+    data: Data
+
+    constructor(id:ODValidId,active:boolean,data:Data){
+        super(id)
+        this.active = active
+        this.data = data
+    }
+}
+
+/**## ODCooldown `class`
+ * This is an Open Discord cooldown.
+ * 
+ * It doesn't do anything on it's own, but it provides the methods that are used to interact with a cooldown.
+ * This class can be extended from to create a working cooldown.
+ * 
+ * There are also premade cooldowns available in the bot!
+ */
+export class ODCooldown<Data extends object> extends ODManagerData {
+    data: ODManager<ODCooldownData<Data>> = new ODManager()
+    /**Is this cooldown already initialized? */
+    ready: boolean = false
+
+    constructor(id:ODValidId){
+        super(id)
+    }
+
+    /**Check this id and start cooldown when it exeeds the limit! Returns `true` when on cooldown! */
+    use(id:string): boolean {
+        throw new ODSystemError("Tried to use an unimplemented ODCooldown!")
+    }
+    /**Check this id without starting or updating the cooldown. Returns `true` when on cooldown! */
+    check(id:string): boolean {
+        throw new ODSystemError("Tried to use an unimplemented ODCooldown!")
+    }
+    /**Remove the cooldown for an id when available.*/
+    delete(id:string){
+        throw new ODSystemError("Tried to use an unimplemented ODCooldown!")
+    }
+    /**Initialize the internal systems of this cooldown. */
+    async init(){
+        throw new ODSystemError("Tried to use an unimplemented ODCooldown!")
+    }
+}
+
+/**## ODCounterCooldown `class`
+ * This is an Open Discord counter cooldown.
+ * 
+ * It is is a cooldown based on a counter. When the number exceeds the limit, the cooldown is activated.
+ * The number will automatically be decreased with a set amount & interval.
+ */
+export class ODCounterCooldown extends ODCooldown<{value:number}> {
+    /**The cooldown will activate when exceeding this limit. */
+    activeLimit: number
+    /**The cooldown will deactivate when below this limit. */
+    cancelLimit: number
+    /**The amount to increase the counter with everytime the cooldown is triggered/updated. */
+    increment: number
+    /**The amount to decrease the counter over time. */
+    decrement: number
+    /**The interval between decrements in milliseconds. */
+    invervalMs: number
+
+    constructor(id:ODValidId, activeLimit:number, cancelLimit:number, increment:number, decrement:number, intervalMs:number){
+        super(id)
+        this.activeLimit = activeLimit
+        this.cancelLimit = cancelLimit
+        this.increment = increment
+        this.decrement = decrement
+        this.invervalMs = intervalMs
+    }
+
+    use(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            if (cooldown.active){
+                return true
+
+            }else if (cooldown.data.value < this.activeLimit){
+                cooldown.data.value = cooldown.data.value + this.increment
+                return false
+
+            }else{
+                cooldown.active = true
+                return false
+            }
+        }else{
+            //cooldown for this id doesn't exist
+            this.data.add(new ODCooldownData(id,(this.increment >= this.activeLimit),{
+                value:this.increment
+            }))
+            return false
+        }
+    }
+    check(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            return cooldown.active
+        }else return false
+    }
+    delete(id:string): void {
+        this.data.remove(id)
+    }
+    async init(){
+        if (this.ready) return
+        setInterval(async () => {
+            await this.data.loopAll((cooldown) => {
+                cooldown.data.value = cooldown.data.value - this.decrement
+                if (cooldown.data.value <= this.cancelLimit){
+                    cooldown.active = false
+                }
+                if (cooldown.data.value <= 0){
+                    this.data.remove(cooldown.id)
+                }
+            })
+        },this.invervalMs)
+        this.ready = true
+    }
+}
+
+/**## ODIncrementalCounterCooldown `class`
+ * This is an Open Discord incremental counter cooldown.
+ * 
+ * It is is a cooldown based on an incremental counter. It is exactly the same as the normal counter,
+ * with the only difference being that it still increments when the limit is already exeeded.
+ */
+export class ODIncrementalCounterCooldown extends ODCooldown<{value:number}> {
+    /**The cooldown will activate when exceeding this limit. */
+    activeLimit: number
+    /**The cooldown will deactivate when below this limit. */
+    cancelLimit: number
+    /**The amount to increase the counter with everytime the cooldown is triggered/updated. */
+    increment: number
+    /**The amount to decrease the counter over time. */
+    decrement: number
+    /**The interval between decrements in milliseconds. */
+    invervalMs: number
+
+    constructor(id:ODValidId, activeLimit:number, cancelLimit:number, increment:number, decrement:number, intervalMs:number){
+        super(id)
+        this.activeLimit = activeLimit
+        this.cancelLimit = cancelLimit
+        this.increment = increment
+        this.decrement = decrement
+        this.invervalMs = intervalMs
+    }
+
+    use(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            if (cooldown.active){
+                cooldown.data.value = cooldown.data.value + this.increment
+                return true
+
+            }else if (cooldown.data.value < this.activeLimit){
+                cooldown.data.value = cooldown.data.value + this.increment
+                return false
+
+            }else{
+                cooldown.active = true
+                return false
+            }
+        }else{
+            //cooldown for this id doesn't exist
+            this.data.add(new ODCooldownData(id,(this.increment >= this.activeLimit),{
+                value:this.increment
+            }))
+            return false
+        }
+    }
+    check(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            return cooldown.active
+        }else return false
+    }
+    delete(id:string): void {
+        this.data.remove(id)
+    }
+    async init(){
+        if (this.ready) return
+        setInterval(async () => {
+            await this.data.loopAll((cooldown) => {
+                cooldown.data.value = cooldown.data.value - this.decrement
+                if (cooldown.data.value <= this.cancelLimit){
+                    cooldown.active = false
+                }
+                if (cooldown.data.value <= 0){
+                    this.data.remove(cooldown.id)
+                }
+            })
+        },this.invervalMs)
+        this.ready = true
+    }
+}
+
+/**## ODTimeoutCooldown `class`
+ * This is an Open Discord timeout cooldown.
+ * 
+ * It is a cooldown based on a timer. When triggered/updated, the cooldown is activated for the set amount of time.
+ * After the timer has timed out, the cooldown will be deleted.
+ */
+export class ODTimeoutCooldown extends ODCooldown<{date:number}> {
+    /**The amount of milliseconds before the cooldown times-out */
+    timeoutMs: number
+
+    constructor(id:ODValidId, timeoutMs:number){
+        super(id)
+        this.timeoutMs = timeoutMs
+    }
+
+    use(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            if ((new Date().getTime() - cooldown.data.date) > this.timeoutMs){
+                this.data.remove(id)
+                return false
+            }else{
+                return true
+            }
+        }else{
+            //cooldown for this id doesn't exist
+            this.data.add(new ODCooldownData(id,true,{
+                date:new Date().getTime()
+            }))
+            return false
+        }
+    }
+    check(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            return true
+        }else return false
+    }
+    delete(id:string): void {
+        this.data.remove(id)
+    }
+    /**Get the remaining amount of milliseconds before the timeout stops. */
+    remaining(id:string): number|null {
+        const cooldown = this.data.get(id)
+        if (!cooldown) return null
+        const rawResult = this.timeoutMs - (new Date().getTime() - cooldown.data.date)
+        return (rawResult > 0) ? rawResult : 0
+    }
+    async init(){
+        if (this.ready) return
+        this.ready = true
+    }
+}
+
+/**## ODIncrementalTimeoutCooldown `class`
+ * This is an Open Discord incremental timeout cooldown.
+ * 
+ * It is is a cooldown based on an incremental timer. It is exactly the same as the normal timer,
+ * with the only difference being that it adds additional time when triggered/updated while the cooldown is already active.
+ */
+export class ODIncrementalTimeoutCooldown extends ODCooldown<{date:number}> {
+    /**The amount of milliseconds before the cooldown times-out */
+    timeoutMs: number
+    /**The amount of milliseconds to add when triggered/updated while the cooldown is already active. */
+    incrementMs: number
+
+    constructor(id:ODValidId, timeoutMs:number, incrementMs:number){
+        super(id)
+        this.timeoutMs = timeoutMs
+        this.incrementMs = incrementMs
+    }
+
+    use(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            if ((new Date().getTime() - cooldown.data.date) > this.timeoutMs){
+                this.data.remove(id)
+                return false
+            }else{
+                cooldown.data.date = cooldown.data.date + this.incrementMs
+                return true
+            }
+        }else{
+            //cooldown for this id doesn't exist
+            this.data.add(new ODCooldownData(id,true,{
+                date:new Date().getTime()
+            }))
+            return false
+        }
+    }
+    check(id:string): boolean {
+        const cooldown = this.data.get(id)
+        if (cooldown){
+            //cooldown for this id already exists
+            return true
+        }else return false
+    }
+    delete(id:string): void {
+        this.data.remove(id)
+    }
+    /**Get the remaining amount of milliseconds before the timeout stops. */
+    remaining(id:string): number|null {
+        const cooldown = this.data.get(id)
+        if (!cooldown) return null
+        const rawResult = this.timeoutMs - (new Date().getTime() - cooldown.data.date)
+        return (rawResult > 0) ? rawResult : 0
+    }
+    async init(){
+        if (this.ready) return
+        this.ready = true
+    }
+}

package/src/api/modules/database.ts

@@ -0,0 +1,278 @@
+///////////////////////////////////////
+//DATABASE MODULE
+///////////////////////////////////////
+import { ODId, ODManager, ODManagerData, ODOptionalPromise, ODPromiseVoid, ODSystemError, ODValidId, ODValidJsonType } from "./base"
+import fs from "fs"
+import nodepath from "path"
+import { ODDebugger } from "./console"
+import * as fjs from "formatted-json-stringify"
+
+/**## ODDatabaseManager `class`
+ * This is an Open Discord database manager.
+ * 
+ * It manages all databases in the bot and allows to permanently store data from the bot!
+ * 
+ * You can use this class to get/add a database (`ODDatabase`) in your plugin!
+ */
+export class ODDatabaseManager extends ODManager<ODDatabase> {
+    constructor(debug:ODDebugger){
+        super(debug,"database")
+    }
+    
+    /**Init all database files. */
+    async init(){
+        for (const database of this.getAll()){
+            try{
+                await database.init()
+            }catch(err){
+                process.emit("uncaughtException",new ODSystemError(err))
+            }
+        }
+    }
+}
+
+/**## ODDatabase `class`
+ * This is an Open Discord database template.
+ * This class doesn't do anything at all, it just gives a template & basic methods for a database. Use `ODJsonDatabase` instead!
+ * 
+ * You can use this class if you want to create your own database implementation (e.g. `mongodb`, `mysql`,...)!
+ */
+export class ODDatabase extends ODManagerData {
+    /**The name of the file with extension. */
+    file: string = ""
+    /**The path to the file relative to the main directory. */
+    path: string = ""
+
+    /**Init the database. */
+    init(): ODPromiseVoid {
+        //nothing
+    }
+    /**Add/Overwrite a specific category & key in the database. Returns `true` when overwritten. */
+    set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean> {
+        return false
+    }
+    /**Get a specific category & key in the database */
+    get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined> {
+        return undefined
+    }
+    /**Delete a specific category & key in the database */
+    delete(category:string, key:string): ODOptionalPromise<boolean> {
+        return false
+    }
+    /**Check if a specific category & key exists in the database */
+    exists(category:string, key:string): ODOptionalPromise<boolean> {
+        return false
+    }
+    /**Get a specific category in the database */
+    getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined> {
+        return undefined
+    }
+    /**Get all values in the database */
+    getAll(): ODOptionalPromise<ODJsonDatabaseStructure> {
+        return []
+    }
+}
+
+/**## ODJsonDatabaseStructure `type`
+ * This is the structure of how a JSON database file!
+ */
+export type ODJsonDatabaseStructure = {category:string, key:string, value:ODValidJsonType}[]
+
+/**## ODJsonDatabase `class`
+ * This is an Open Discord JSON database.
+ * It stores data in a `json` file as a large `Array` using the `category`, `key`, `value` strategy.
+ * You can store the following types: `string`, `number`, `boolean`, `array`, `object` & `null`!
+ * 
+ * You can use this class if you want to add your own database or to use an existing one!
+ */
+export class ODJsonDatabase extends ODDatabase {
+    constructor(id:ODValidId, file:string, customPath?:string){
+        super(id)
+        this.file = (file.endsWith(".json")) ? file : file+".json"
+        this.path = customPath ? nodepath.join("./",customPath,this.file) : nodepath.join("./database/",this.file)
+    }
+
+    /**Init the database. */
+    init(): ODPromiseVoid {
+        this.#system.getData()
+    }
+    /**Set/overwrite the value of `category` & `key`. Returns `true` when overwritten!
+     * @example
+     * const didOverwrite = database.setData("category","key","value") //value can be any of the valid types
+     * //You need an ODJsonDatabase class named "database" for this example to work!
+     */
+    set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean> {
+        const currentList = this.#system.getData()
+        const currentData = currentList.find((d) => (d.category === category) && (d.key === key))
+        
+        //overwrite when already present
+        if (currentData){
+            currentList[currentList.indexOf(currentData)].value = value
+        }else{
+            currentList.push({category,key,value})
+        }
+
+        this.#system.setData(currentList)
+        return currentData ? true : false
+    }
+    /**Get the value of `category` & `key`. Returns `undefined` when non-existent!
+     * @example
+     * const data = database.getData("category","key") //data will be the value
+     * //You need an ODJsonDatabase class named "database" for this example to work!
+     */
+    get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined> {
+        const currentList = this.#system.getData()
+        const tempresult = currentList.find((d) => (d.category === category) && (d.key === key))
+        return tempresult ? tempresult.value : undefined
+    }
+    /**Remove the value of `category` & `key`. Returns `undefined` when non-existent!
+     * @example
+     * const didExist = database.deleteData("category","key") //delete this value
+     * //You need an ODJsonDatabase class named "database" for this example to work!
+     */
+    delete(category:string, key:string): ODOptionalPromise<boolean> {
+        const currentList = this.#system.getData()
+        const currentData = currentList.find((d) => (d.category === category) && (d.key === key))
+        if (currentData) currentList.splice(currentList.indexOf(currentData),1)
+
+        this.#system.setData(currentList)
+        return currentData ? true : false
+    }
+    /**Check if a value of `category` & `key` exists. Returns `false` when non-existent! */
+    exists(category:string, key:string): ODOptionalPromise<boolean> {
+        const currentList = this.#system.getData()
+        const tempresult = currentList.find((d) => (d.category === category) && (d.key === key))
+        return tempresult ? true : false
+    }
+    /**Get all values in `category`. Returns `undefined` when non-existent! */
+    getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined> {
+        const currentList = this.#system.getData()
+        const tempresult = currentList.filter((d) => (d.category === category))
+        return tempresult ? tempresult.map((data) => {return {key:data.key,value:data.value}}) : undefined
+    }
+    /**Get all values in `category`. */
+    getAll(): ODOptionalPromise<ODJsonDatabaseStructure> {
+        return this.#system.getData()
+    }
+
+    #system = {
+        /**Read parsed data from the json file */
+        getData: (): ODJsonDatabaseStructure => {
+            if (fs.existsSync(this.path)){
+                try{
+                    return JSON.parse(fs.readFileSync(this.path).toString())
+                }catch(err){
+                    process.emit("uncaughtException",err)
+                    throw new ODSystemError("Unable to read database "+this.path+"! getData() read error. (see error above)")
+                }
+            }else{
+                fs.writeFileSync(this.path,"[]")
+                return []
+            }
+        },
+        /**Write parsed data to the json file */
+        setData: (data:ODJsonDatabaseStructure) => {
+            fs.writeFileSync(this.path,JSON.stringify(data,null,"\t"))
+        }
+    }
+}
+
+
+/**## ODFormattedJsonDatabase `class`
+ * This is an Open Discord Formatted JSON database.
+ * It stores data in a `json` file as a large `Array` using the `category`, `key`, `value` strategy.
+ * You can store the following types: `string`, `number`, `boolean`, `array`, `object` & `null`!
+ * 
+ * This one is exactly the same as `ODJsonDatabase`, but it has a formatter from the `formatted-json-stringify` package.
+ * This can help you organise it a little bit better!
+ */
+export class ODFormattedJsonDatabase extends ODDatabase {
+    /**The formatter to use on the database array */
+    formatter: fjs.ArrayFormatter
+
+    constructor(id:ODValidId, file:string, formatter:fjs.ArrayFormatter, customPath?:string){
+        super(id)
+        this.file = (file.endsWith(".json")) ? file : file+".json"
+        this.path = customPath ? nodepath.join("./",customPath,this.file) : nodepath.join("./database/",this.file)
+        this.formatter = formatter
+    }
+
+    /**Init the database. */
+    init(): ODPromiseVoid {
+        this.#system.getData()
+    }
+    /**Set/overwrite the value of `category` & `key`. Returns `true` when overwritten!
+     * @example
+     * const didOverwrite = database.setData("category","key","value") //value can be any of the valid types
+     * //You need an ODFormattedJsonDatabase class named "database" for this example to work!
+     */
+    set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean> {
+        const currentList = this.#system.getData()
+        const currentData = currentList.find((d) => (d.category === category) && (d.key === key))
+        
+        //overwrite when already present
+        if (currentData){
+            currentList[currentList.indexOf(currentData)].value = value
+        }else{
+            currentList.push({category,key,value})
+        }
+
+        this.#system.setData(currentList)
+        return currentData ? true : false
+    }
+    /**Get the value of `category` & `key`. Returns `undefined` when non-existent!
+     * @example
+     * const data = database.getData("category","key") //data will be the value
+     * //You need an ODFormattedJsonDatabase class named "database" for this example to work!
+     */
+    get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined> {
+        const currentList = this.#system.getData()
+        const tempresult = currentList.find((d) => (d.category === category) && (d.key === key))
+        return tempresult ? tempresult.value : undefined
+    }
+    /**Remove the value of `category` & `key`. Returns `undefined` when non-existent!
+     * @example
+     * const didExist = database.deleteData("category","key") //delete this value
+     * //You need an ODFormattedJsonDatabase class named "database" for this example to work!
+     */
+    delete(category:string, key:string): ODOptionalPromise<boolean> {
+        const currentList = this.#system.getData()
+        const currentData = currentList.find((d) => (d.category === category) && (d.key === key))
+        if (currentData) currentList.splice(currentList.indexOf(currentData),1)
+
+        this.#system.setData(currentList)
+        return currentData ? true : false
+    }
+    /**Check if a value of `category` & `key` exists. Returns `false` when non-existent! */
+    exists(category:string, key:string): ODOptionalPromise<boolean> {
+        const currentList = this.#system.getData()
+        const tempresult = currentList.find((d) => (d.category === category) && (d.key === key))
+        return tempresult ? true : false
+    }
+    /**Get all values in `category`. Returns `undefined` when non-existent! */
+    getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined> {
+        const currentList = this.#system.getData()
+        const tempresult = currentList.filter((d) => (d.category === category))
+        return tempresult ? tempresult.map((data) => {return {key:data.key,value:data.value}}) : undefined
+    }
+    /**Get all values in `category`. */
+    getAll(): ODOptionalPromise<ODJsonDatabaseStructure> {
+        return this.#system.getData()
+    }
+
+    #system = {
+        /**Read parsed data from the json file */
+        getData: (): ODJsonDatabaseStructure => {
+            if (fs.existsSync(this.path)){
+                return JSON.parse(fs.readFileSync(this.path).toString())
+            }else{
+                fs.writeFileSync(this.path,"[]")
+                return []
+            }
+        },
+        /**Write parsed data to the json file */
+        setData: (data:ODJsonDatabaseStructure) => {
+            fs.writeFileSync(this.path,this.formatter.stringify(data))
+        }
+    }
+}