@open-discord-bots/framework 0.2.17 → 0.3.0

package/src/api/modules/config.ts

@@ -6,6 +6,7 @@ import nodepath from "path"
 import { ODDebugger } from "./console.js"
 import fs from "fs"
 import * as fjs from "formatted-json-stringify"
+import { jsonc } from "jsonc"
 
 /**## ODConfigManagerIdConstraint `type`
  * The constraint/layout for id mappings/interfaces of the `ODConfigManager` class.
@@ -71,7 +72,7 @@ export class ODConfigManager<IdList extends ODConfigManagerIdConstraint = ODConf
  * 
  * You can use this class if you want to create your own config implementation (e.g. `yml`, `xml`,...)!
  */
-export class ODConfig<Data extends any> extends ODManagerData {
+export abstract class ODConfig<Data extends any> extends ODManagerData {
     /**The name of the file with extension. */
     file: string = ""
     /**The path to the file relative to the main directory. */
@@ -182,4 +183,80 @@ export class ODJsonConfig<Data extends any> extends ODConfig<Data> {
             throw new ODSystemError("Unable to save config \""+nodepath.join("./",this.path)+"\"!")
         }
     }
+}
+
+/**## ODJsonCommentsConfig `class`
+ * An Open Discord JSONC (`.jsonc`) config.  
+ * Use this class to get & edit variables from the config files or to create your own JSON config!
+ * @example
+ * //create a config from: ./config/test.jsonc with the id "some-config"
+ * const config = new api.ODJsonCommentsConfig("some-config","test.jsonc")
+ * 
+ * //create a config with custom dir: ./plugins/testplugin/test.jsonc
+ * const config = new api.ODJsonCommentsConfig("plugin-config","test.jsonc","./plugins/testplugin/")
+ */
+export class ODJsonCommentsConfig<Data extends any> extends ODConfig<Data> {
+    formatter: fjs.custom.BaseFormatter
+
+    constructor(id:ODValidId, file:string, customPath?:string, formatter?:fjs.custom.BaseFormatter){
+        super(id,{})
+        this.file = (file.endsWith(".jsonc")) ? file : file+".jsonc"
+        this.path = customPath ? nodepath.join("./",customPath,this.file) : nodepath.join("./config/",this.file)
+        this.formatter = formatter ?? new fjs.DefaultFormatter(null,true,"    ")
+    }
+
+    /**Init the config. */
+    init(): ODPromiseVoid {
+        if (!fs.existsSync(this.path)) throw new ODSystemError("Unable to parse JSONC config \""+nodepath.join("./",this.path)+"\", the file doesn't exist!")
+        try{
+            this.data = jsonc.parse(fs.readFileSync(this.path).toString())
+            super.init()
+        }catch(err){
+            process.emit("uncaughtException",err)
+            throw new ODSystemError("Unable to parse JSONC config \""+nodepath.join("./",this.path)+"\"!")
+        }
+    }
+    /**Reload the config. Be aware that this doesn't update the config data everywhere in the bot! */
+    reload(){
+        if (!this.initiated) throw new ODSystemError("Unable to reload JSONC config \""+nodepath.join("./",this.path)+"\", the file hasn't been initiated yet!")
+        if (!fs.existsSync(this.path)) throw new ODSystemError("Unable to JSONC reload config \""+nodepath.join("./",this.path)+"\", the file doesn't exist!")
+        try{
+            this.data = jsonc.parse(fs.readFileSync(this.path).toString())
+            super.reload()
+            this.reloadListeners.forEach((cb) => {
+                try{
+                    cb()
+                }catch(err){
+                    process.emit("uncaughtException",err)
+                }
+            })
+        }catch(err){
+            process.emit("uncaughtException",err)
+            throw new ODSystemError("Unable to reload JSONC config \""+nodepath.join("./",this.path)+"\"!")
+        }
+    }
+    /**Save the edited config to the filesystem. This is used by the Interactive Setup CLI. It's not recommended to use this while the bot is running. */
+    save(): ODPromiseVoid {
+        if (!this.initiated) throw new ODSystemError("Unable to save JSONC config \""+nodepath.join("./",this.path)+"\", the file hasn't been initiated yet!")
+        try{
+            const contents = this.formatter.stringify(this.data as ODValidJsonType)
+            fs.writeFileSync(this.path,contents)
+            super.save()
+        }catch(err){
+            process.emit("uncaughtException",err)
+            throw new ODSystemError("Unable to save JSONC config \""+nodepath.join("./",this.path)+"\"!")
+        }
+    }
+}
+
+/**## ODMemoryConfig `class`
+ * An Open Discord memory config.  
+ * This config lives in-memory and does not have any connection to the filesystem.
+ * 
+ * It is perfect for temporary configs or using the `ODChecker` without a real config file.
+ */
+export class ODMemoryConfig<Data extends any> extends ODConfig<Data> {
+    constructor(id:ODValidId,data:Data){
+        super(id,data)
+    }
 }

package/src/api/modules/cooldown.ts

@@ -75,7 +75,7 @@ export class ODCooldownData<Data extends object> extends ODManagerData {
  * 
  * There are also premade cooldowns available in the bot!
  */
-export class ODCooldown<Data extends object> extends ODManagerData {
+export abstract class ODCooldown<Data extends object> extends ODManagerData {
     data: ODManager<ODCooldownData<Data>> = new ODManager()
     /**Is this cooldown already initialized? */
     ready: boolean = false
@@ -85,21 +85,16 @@ export class ODCooldown<Data extends object> extends ODManagerData {
     }
 
     /**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!")
-    }
+    abstract use(id:string): boolean
+    
     /**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!")
-    }
+    abstract check(id:string): boolean
+    
     /**Remove the cooldown for an id when available.*/
-    delete(id:string){
-        throw new ODSystemError("Tried to use an unimplemented ODCooldown!")
-    }
+    abstract delete(id:string): void
+    
     /**Initialize the internal systems of this cooldown. */
-    async init(){
-        throw new ODSystemError("Tried to use an unimplemented ODCooldown!")
-    }
+    abstract init(): Promise<void>|void
 }
 
 /**## ODCounterCooldown `class`

package/src/api/modules/database.ts

@@ -70,50 +70,42 @@ export type ODDatabaseIdConstraint = Record<string,ODValidJsonType>
  * 
  * You can use this class if you want to create your own database implementation (e.g. `mongodb`, `mysql`,...)!
  */
-export class ODDatabase<IdList extends ODDatabaseIdConstraint = ODDatabaseIdConstraint> extends ODManagerData {
+export abstract class ODDatabase<IdList extends ODDatabaseIdConstraint = ODDatabaseIdConstraint> 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
-    }
+    abstract init(): ODPromiseVoid
+    
     /**Add/Overwrite a specific category & key in the database. Returns `true` when overwritten. */
-    set<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId, key:string, value:IdList[CategoryId]): ODOptionalPromise<boolean>
-    set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean>
-    set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean> {
-        return false
-    }
+    abstract set<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId, key:string, value:IdList[CategoryId]): ODOptionalPromise<boolean>
+    abstract set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean>
+    abstract set(category:string, key:string, value:ODValidJsonType): ODOptionalPromise<boolean>
+    
     /**Get a specific category & key in the database */
-    get<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId, key:string): ODOptionalPromise<IdList[CategoryId]|undefined>
-    get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined>
-    get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined> {
-        return undefined
-    }
+    abstract get<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId, key:string): ODOptionalPromise<IdList[CategoryId]|undefined>
+    abstract get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined>
+    abstract get(category:string, key:string): ODOptionalPromise<ODValidJsonType|undefined>
+    
     /**Delete a specific category & key in the database */
-    delete<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId, key:string): ODOptionalPromise<boolean>
-    delete(category:string, key:string): ODOptionalPromise<boolean>
-    delete(category:string, key:string): ODOptionalPromise<boolean> {
-        return false
-    }
+    abstract delete<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId, key:string): ODOptionalPromise<boolean>
+    abstract delete(category:string, key:string): ODOptionalPromise<boolean>
+    abstract delete(category:string, key:string): ODOptionalPromise<boolean>
+    
     /**Check if a specific category & key exists in the database */
-    exists(category:keyof ODNoGeneric<IdList>, key:string): ODOptionalPromise<boolean>
-    exists(category:string, key:string): ODOptionalPromise<boolean>
-    exists(category:string, key:string): ODOptionalPromise<boolean> {
-        return false
-    }
+    abstract exists(category:keyof ODNoGeneric<IdList>, key:string): ODOptionalPromise<boolean>
+    abstract exists(category:string, key:string): ODOptionalPromise<boolean>
+    abstract exists(category:string, key:string): ODOptionalPromise<boolean>
+    
     /**Get a specific category in the database */
-    getCategory<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId): ODOptionalPromise<{key:string, value:IdList[CategoryId]}[]|undefined>
-    getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined>
-    getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined> {
-        return undefined
-    }
+    abstract getCategory<CategoryId extends keyof ODNoGeneric<IdList>>(category:CategoryId): ODOptionalPromise<{key:string, value:IdList[CategoryId]}[]|undefined>
+    abstract getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined>
+    abstract getCategory(category:string): ODOptionalPromise<{key:string, value:ODValidJsonType}[]|undefined>
+    
     /**Get all values in the database */
-    getAll(): ODOptionalPromise<ODJsonDatabaseStructure> {
-        return []
-    }
+    abstract getAll(): ODOptionalPromise<ODJsonDatabaseStructure>
 }
 
 /**## ODJsonDatabaseStructure `type`

package/src/api/modules/helpmenu.ts

@@ -4,27 +4,22 @@
 import { ODId, ODManager, ODManagerData, ODNoGeneric, ODSystemError, ODValidId } from "./base.js"
 import { ODDebugger } from "./console.js"
 
-/**## ODHelpMenuComponentRenderer `type`
- * This is the callback of the help menu component renderer. It also contains information about how & where it is rendered.
- */
-export type ODHelpMenuComponentRenderer = (page:number, category:number, location:number, mode:"slash"|"text") => string|Promise<string>
-
 /**## ODHelpMenuComponent `class`
  * This is an Open Discord help menu component.
  * 
  * It can render something on the Open Discord help menu.
  */
-export class ODHelpMenuComponent extends ODManagerData {
+export abstract class ODHelpMenuComponent extends ODManagerData {
     /**The priority of this component. The higher, the earlier it will appear in the help menu. */
     priority: number
-    /**The render function for this component. */
-    render: ODHelpMenuComponentRenderer
 
-    constructor(id:ODValidId, priority:number, render:ODHelpMenuComponentRenderer){
+    constructor(id:ODValidId, priority:number){
         super(id)
         this.priority = priority
-        this.render = render
     }
+
+    /**The render function for this component. */
+    abstract render(page:number, category:number, location:number, mode:"slash"|"text"): string|Promise<string>
 }
 
 /**## ODHelpMenuTextComponent `class`
@@ -33,10 +28,16 @@ export class ODHelpMenuComponent extends ODManagerData {
  * It can render a static piece of text on the Open Discord help menu.
  */
 export class ODHelpMenuTextComponent extends ODHelpMenuComponent {
+    /**The text of this help menu component. */
+    text: string
+
     constructor(id:ODValidId, priority:number, text:string){
-        super(id,priority,() => {
-            return text
-        })
+        super(id,priority)
+        this.text = text
+    }
+
+    render(page:number,category:number,location:number,mode:"slash"|"text"){
+        return this.text
     }
 }
 
@@ -74,16 +75,22 @@ export interface ODHelpMenuCommandComponentSettings {
  * It contains a useful helper to render a command in the Open Discord help menu.
  */
 export class ODHelpMenuCommandComponent extends ODHelpMenuComponent {
+    /**The settings for this help menu component. */
+    settings:ODHelpMenuCommandComponentSettings
+
     constructor(id:ODValidId, priority:number, settings:ODHelpMenuCommandComponentSettings){
-        super(id,priority,(page,category,location,mode) => {
-            if (mode == "slash" && settings.slashName){
-                return `\`${settings.slashName}${(settings.slashOptions) ? this.#renderOptions(settings.slashOptions) : ""}\` ➜ ${settings.slashDescription ?? ""}`
-            
-            }else if (mode == "text" && settings.textName){
-                return `\`${settings.textName}${(settings.textOptions) ? this.#renderOptions(settings.textOptions) : ""}\` ➜ ${settings.textDescription ?? ""}`
-            
-            }else return ""
-        })
+        super(id,priority)
+        this.settings = settings
+    }
+
+    render(page:number,category:number,location:number,mode:"slash"|"text"){
+        if (mode == "slash" && this.settings.slashName){
+            return `\`${this.settings.slashName}${(this.settings.slashOptions) ? this.#renderOptions(this.settings.slashOptions) : ""}\` ➜ ${this.settings.slashDescription ?? ""}`
+        
+        }else if (mode == "text" && this.settings.textName){
+            return `\`${this.settings.textName}${(this.settings.textOptions) ? this.#renderOptions(this.settings.textOptions) : ""}\` ➜ ${this.settings.textDescription ?? ""}`
+        
+        }else return ""
     }
     
     /**Utility function to render all command options. */

package/src/api/modules/language.ts

@@ -45,9 +45,9 @@ export class ODLanguageManager<IdList extends ODLanguageManagerIdConstraint = OD
     
     constructor(debug:ODDebugger, presets:boolean){
         super(debug,"language")
-        if (presets) this.add(new ODLanguage("english","english.json"))
-        this.current = presets ? new ODLanguage("english","english.json") : null
-        this.backup = presets ? new ODLanguage("english","english.json") : null
+        if (presets) this.add(new ODJsonLanguage("english","english.json"))
+        this.current = presets ? new ODJsonLanguage("english","english.json") : null
+        this.backup = presets ? new ODJsonLanguage("english","english.json") : null
         this.#debug = debug
     }
 
@@ -185,7 +185,7 @@ export class ODLanguageManager<IdList extends ODLanguageManagerIdConstraint = OD
  * 
  * JSON languages should be created using the `ODJsonLanguage` class instead!
  */
-export class ODLanguage extends ODManagerData {
+export abstract class ODLanguage extends ODManagerData {
     /**The name of the file with extension. */
     file: string = ""
     /**The path to the file relative to the main directory. */
@@ -201,9 +201,7 @@ export class ODLanguage extends ODManagerData {
     }
 
     /**Init the language. */
-    init(): ODPromiseVoid {
-        //nothing
-    }
+    abstract init(): ODPromiseVoid
 }
 
 /**## ODJsonLanguage `class`

package/src/api/modules/progressbar.ts

@@ -119,14 +119,13 @@ export class ODProgressBarRenderer<Settings extends {}> extends ODManagerData {
             return "<PROGRESS-BAR-ERROR>"
         }
     }
-
+    /**Create a clone of this progress bar renderer, but with additional settings. */
     withAdditionalSettings(settings:Partial<Settings>): ODProgressBarRenderer<Settings> {
         const newSettings: Settings = {...this.settings}
         for (const key of Object.keys(settings) as (keyof Partial<Settings>)[]){
             if (typeof settings[key] != "undefined") newSettings[key] = settings[key]
         }
 
-        const idk = Object.keys(settings)
         return new ODProgressBarRenderer(this.id,this.#render,newSettings)
     }
 }
@@ -139,7 +138,7 @@ export class ODProgressBarRenderer<Settings extends {}> extends ODManagerData {
  * 
  * Use other classes as existing templates or create your own progress bar from scratch using this class.
  */
-export class ODProgressBar extends ODManagerData {
+export abstract class ODProgressBar extends ODManagerData {
     /**The renderer of this progress bar. */
     renderer: ODProgressBarRenderer<{}>
     /**Is this progress bar currently active? */

package/src/api/modules/responder.ts

@@ -15,7 +15,7 @@ import { ODDropdownData, ODMessageBuildResult, ODMessageBuildSentResult, ODModal
  * 
  * This class can't be used stand-alone & needs to be extended from!
  */
-export class ODResponderImplementation<Instance,Origin extends string,Params,WorkerIds extends string = string> extends ODManagerData {
+export abstract class ODResponderImplementation<Instance,Origin extends string,Params,WorkerIds extends string = string> extends ODManagerData {
     /**The manager that has all workers of this implementation */
     workers: ODWorkerManager<Instance,Origin,Params,WorkerIds>
     /**The `commandName` or `customId` needs to match this string or regex for this responder to be executed. */
@@ -28,9 +28,7 @@ export class ODResponderImplementation<Instance,Origin extends string,Params,Wor
         if (callback) this.workers.add(new ODWorker(callbackId ? callbackId : id,priority ?? 0,callback))
     }
     /**Execute all workers & return the result. */
-    async respond(instance:Instance, origin:Origin, params:Params): Promise<void> {
-        throw new ODSystemError("Tried to build an unimplemented ODResponderImplementation")
-    }
+    abstract respond(instance:Instance, origin:Origin, params:Params): Promise<void>
 }
 
 /**## ODResponderTimeoutErrorCallback `type`

package/src/api/modules/session.ts

@@ -67,7 +67,7 @@ export type ODSessionTimeoutCallback = (id:string, timeout:"default"|"custom", d
 /**## ODSession `class`
  * This is an Open Discord session.
  * 
- * It can be used to create 100% unique id's for usage in the bot. An id can also store additional data which isn't saved to the filesystem.
+ * It can be used to create unique user sessions with an ID. Each session can store additional data which isn't saved to the filesystem.
  * You can almost compare it to the PHP session system.
  */
 export class ODSession extends ODManagerData {

package/src/api/modules/startscreen.ts

@@ -90,20 +90,22 @@ export class ODStartScreenManager<IdList extends ODStartScreenManagerIdConstrain
  * 
  * It's recommended to use pre-built components except if you really need a custom one.
  */
-export class ODStartScreenComponent extends ODManagerData {
+export abstract class ODStartScreenComponent extends ODManagerData {
     /**The priority of this component. */
     priority: number
     /**An optional render function which will be inserted before the default renderer. */
-    renderBefore: ODStartScreenComponentRenderCallback|null = null
+    renderBefore: ODStartScreenComponentRenderCallback|null
     /**The render function which will render the contents of this component. */
     render: ODStartScreenComponentRenderCallback
     /**An optional render function which will be inserted behind the default renderer. */
-    renderAfter: ODStartScreenComponentRenderCallback|null = null
+    renderAfter: ODStartScreenComponentRenderCallback|null
 
-    constructor(id:ODValidId, priority:number, render:ODStartScreenComponentRenderCallback){
+    constructor(id:ODValidId, priority:number, render:ODStartScreenComponentRenderCallback,renderBefore?:ODStartScreenComponentRenderCallback,renderAfter?:ODStartScreenComponentRenderCallback){
         super(id)
         this.priority = priority
         this.render = render
+        this.renderBefore = renderBefore ?? null
+        this.renderAfter = renderAfter ?? null
     }
 
     /**Render this component and combine it with the `renderBefore` & `renderAfter` contents. */