@open-discord-bots/framework 0.0.1 → 0.0.2

package/src/api/modules/helpmenu.ts

@@ -0,0 +1,216 @@
+///////////////////////////////////////
+//HELP MODULE
+///////////////////////////////////////
+import { ODId, ODManager, ODManagerData, ODValidId } from "./base"
+import { ODDebugger } from "./console"
+
+/**## 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 {
+    /**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){
+        super(id)
+        this.priority = priority
+        this.render = render
+    }
+}
+
+/**## ODHelpMenuTextComponent `class`
+ * This is an Open Discord help menu text component.
+ * 
+ * It can render a static piece of text on the Open Discord help menu.
+ */
+export class ODHelpMenuTextComponent extends ODHelpMenuComponent {
+    constructor(id:ODValidId, priority:number, text:string){
+        super(id,priority,() => {
+            return text
+        })
+    }
+}
+
+/**## ODHelpMenuCommandComponentOption `interface`
+ * This interface contains a command option for the `ODHelpMenuCommandComponent`.
+ */
+export interface ODHelpMenuCommandComponentOption {
+    /**The name of this option. */
+    name:string,
+    /**Is this option optional? */
+    optional:boolean
+}
+
+/**## ODHelpMenuCommandComponentSettings `interface`
+ * This interface contains the settings for the `ODHelpMenuCommandComponent`.
+ */
+export interface ODHelpMenuCommandComponentSettings {
+    /**The name of this text command. */
+    textName?:string,
+    /**The name of this slash command. */
+    slashName?:string,
+    /**Options available in the text command. */
+    textOptions?:ODHelpMenuCommandComponentOption[],
+    /**Options available in the slash command. */
+    slashOptions?:ODHelpMenuCommandComponentOption[],
+    /**The description for the text command. */
+    textDescription?:string,
+    /**The description for the slash command. */
+    slashDescription?:string
+}
+
+/**## ODHelpMenuCommandComponent `class`
+ * This is an Open Discord help menu command component.
+ * 
+ * It contains a useful helper to render a command in the Open Discord help menu.
+ */
+export class ODHelpMenuCommandComponent extends ODHelpMenuComponent {
+    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 ""
+        })
+    }
+    
+    /**Utility function to render all command options. */
+    #renderOptions(options:ODHelpMenuCommandComponentOption[]){
+        return " "+options.map((opt) => (opt.optional) ? `[${opt.name}]` : `<${opt.name}>`).join(" ")
+    }
+}
+
+/**## ODHelpMenuCategory `class`
+ * This is an Open Discord help menu category.
+ * 
+ * Every category in the help menu is an embed field by default.
+ * Try to limit the amount of components per category.
+ */
+export class ODHelpMenuCategory extends ODManager<ODHelpMenuComponent> {
+    /**The id of this category. */
+    id: ODId
+    /**The priority of this category. The higher, the earlier it will appear in the menu. */
+    priority: number
+    /**The name of this category. (can include emoji's) */
+    name: string
+    /**When enabled, it automatically starts this category on a new page. */
+    newPage: boolean
+
+    constructor(id:ODValidId, priority:number, name:string, newPage?:boolean){
+        super()
+        this.id = new ODId(id)
+        this.priority = priority
+        this.name = name
+        this.newPage = newPage ?? false
+    }
+
+    /**Render this category and it's components. */
+    async render(page:number, category:number, mode:"slash"|"text"){
+        //sort from high priority to low
+        const derefArray = [...this.getAll()]
+        derefArray.sort((a,b) => {
+            return b.priority-a.priority
+        })
+        const result: string[] = []
+
+        let i = 0
+        for (const component of derefArray){
+            try {
+                result.push(await component.render(page,category,i,mode))
+            }catch(err){
+                process.emit("uncaughtException",err)
+            }
+            i++
+        }
+
+        //only return the non-empty components
+        return result.filter((component) => component !== "").join("\n\n")
+    }
+}
+
+/**## ODHelpMenuRenderResult `type`
+ * This is the array returned when the help menu has been rendered successfully.
+ * 
+ * It contains a list of pages, which contain categories by name & value (content).
+ */
+export type ODHelpMenuRenderResult = {name:string, value:string}[][]
+
+/**## ODHelpMenuManager `class`
+ * This is an Open Discord help menu manager.
+ * 
+ * It is responsible for rendering the entire help menu content.
+ * You are also able to configure the amount of categories per page here.
+ * 
+ * Fewer Categories == More Clean Menu
+ */
+export class ODHelpMenuManager extends ODManager<ODHelpMenuCategory> {
+    /**Alias to Open Discord debugger. */
+    #debug: ODDebugger
+    /**The amount of categories per-page. */
+    categoriesPerPage: number = 3
+    
+    constructor(debug:ODDebugger){
+        super(debug,"help menu category")
+        this.#debug = debug
+    }
+
+    add(data:ODHelpMenuCategory, overwrite?:boolean): boolean {
+        data.useDebug(this.#debug,"help menu component")
+        return super.add(data,overwrite)
+    }
+
+    /**Render this entire help menu & return a `ODHelpMenuRenderResult`. */
+    async render(mode:"slash"|"text"): Promise<ODHelpMenuRenderResult> {
+        //sort from high priority to low
+        const derefArray = [...this.getAll()]
+        derefArray.sort((a,b) => {
+            return b.priority-a.priority
+        })
+        const result: {name:string, value:string}[][] = []
+        let currentPage: {name:string, value:string}[] = []
+
+        for (const category of derefArray){
+            try {
+                const renderedCategory = await category.render(result.length,currentPage.length,mode)
+
+                if (renderedCategory !== ""){
+                    //create new page when category wants to
+                    if (currentPage.length > 0 && category.newPage){
+                        result.push(currentPage)
+                        currentPage = []
+                    }
+
+                    currentPage.push({
+                        name:category.name,
+                        value:renderedCategory
+                    })
+
+                    //create new page when page is full
+                    if (currentPage.length >= this.categoriesPerPage){
+                        result.push(currentPage)
+                        currentPage = []
+                    }
+                }
+            }catch(err){
+                process.emit("uncaughtException",err)
+            }
+        }
+
+        //push current page when not-empty
+        if (currentPage.length > 0) result.push(currentPage)
+
+        return result
+    }
+}

package/src/api/modules/language.ts

@@ -0,0 +1,201 @@
+///////////////////////////////////////
+//LANGUAGE MODULE
+///////////////////////////////////////
+import { ODId, ODManager, ODManagerData, ODPromiseVoid, ODSystemError, ODValidId } from "./base"
+import nodepath from "path"
+import { ODDebugger } from "./console"
+import fs from "fs"
+
+/**## ODLanguageMetadata `interface`
+ * This interface contains all metadata available in the language files.
+ */
+export interface ODLanguageMetadata {
+    /**The version of Open Discord this translation is made for. */
+    otversion:string,
+    /**The name of the language in english (with capital letter). */
+    language:string,
+    /**A list of translators (discord/github username) who've contributed to this language. */
+    translators:string[],
+    /**The last date that this translation has been modified (format: DD/MM/YYYY) */
+    lastedited:string,
+    /**When `true`, the translator made use of some sort of automation while creating the translation. (e.g. ChatGPT, Google Translate, DeepL, ...) */
+    automated:boolean
+}
+
+/**## ODLanguageManager `class`
+ * This is an Open Discord language manager.
+ * 
+ * It manages all languages in the bot and manages translation for you!
+ * Get a translation via the `getTranslation()` or `getTranslationWithParams()` methods.
+ * 
+ * Add new languages using the `ODlanguage` class in your plugin!
+ */
+export class ODLanguageManager extends ODManager<ODLanguage> {
+    /**The currently selected language. */
+    current: ODLanguage|null = null
+    /**The currently selected backup language. (used when translation missing in current language) */
+    backup: ODLanguage|null = null
+    /**An alias to Open Discord debugger. */
+    #debug: ODDebugger
+    
+    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
+        this.#debug = debug
+    }
+
+    /**Set the current language by providing the ID of a language which is registered in this manager. */
+    setCurrentLanguage(id:ODValidId){
+        this.current = this.get(id)
+        const languageId = this.current?.id.value ?? "<unknown-id>"
+        const languageAutomated = this.current?.metadata?.automated.toString() ?? "<unknown-metadata>"
+        this.#debug.debug("Selected current language",[
+            {key:"id",value:languageId},
+            {key:"automated",value:languageAutomated},
+        ])
+    }
+    /**Get the current language (same as `this.current`) */
+    getCurrentLanguage(){
+        return (this.current) ? this.current : null
+    }
+    /**Set the backup language by providing the ID of a language which is registered in this manager. */
+    setBackupLanguage(id:ODValidId){
+        this.backup = this.get(id)
+        const languageId = this.backup?.id.value ?? "<unknown-id>"
+        const languageAutomated = this.backup?.metadata?.automated.toString() ?? "<unknown-metadata>"
+        this.#debug.debug("Selected backup language",[
+            {key:"id",value:languageId},
+            {key:"automated",value:languageAutomated},
+        ])
+    }
+    /**Get the backup language (same as `this.backup`) */
+    getBackupLanguage(){
+        return (this.backup) ? this.backup : null
+    }
+    /**Get the metadata of the current/backup language. */
+    getLanguageMetadata(frombackup?:boolean): ODLanguageMetadata|null {
+        if (frombackup) return (this.backup) ? this.backup.metadata : null
+        return (this.current) ? this.current.metadata : null
+    }
+    /**Get the ID (string) of the current language. (Not backup language) */
+    getCurrentLanguageId(){
+        return (this.current) ? this.current.id.value : ""
+    }
+    /**Get a translation string by JSON location. (e.g. `"checker.system.typeError"`) */
+    getTranslation(id:string): string|null {
+        if (!this.current) return this.#getBackupTranslation(id)
+        
+        const splitted = id.split(".")
+        let currentObject = this.current.data
+        let result: string|false = false
+        splitted.forEach((id) => {
+            if (typeof currentObject[id] == "object"){
+                currentObject = currentObject[id]
+            }else if (typeof currentObject[id] == "string"){
+                result = currentObject[id]
+            }
+        })
+
+        if (typeof result == "string") return result
+        else return this.#getBackupTranslation(id)
+    }
+    /**Get a backup  translation string by JSON location. (system only) */
+    #getBackupTranslation(id:string): string|null {
+        if (!this.backup) return null
+
+        const splitted = id.split(".")
+        let currentObject = this.backup.data
+        let result: string|false = false
+        splitted.forEach((id) => {
+            if (typeof currentObject[id] == "object"){
+                currentObject = currentObject[id]
+            }else if (typeof currentObject[id] == "string"){
+                result = currentObject[id]
+            }
+        })
+
+        if (typeof result == "string") return result
+        else return null
+    }
+    /**Get a backup translation string by JSON location and replace `{0}`,`{1}`,`{2}`,... with the provided parameters. */
+    getTranslationWithParams(id:string, params:string[]): string|null {
+        let translation = this.getTranslation(id)
+        if (!translation) return translation
+
+        params.forEach((value,index) => {
+            if (!translation) return
+            translation = translation.replace(`{${index}}`,value)
+        })
+        return translation
+    }
+
+    /**Init all language files. */
+    async init(){
+        for (const language of this.getAll()){
+            try{
+                await language.init()
+            }catch(err){
+                process.emit("uncaughtException",new ODSystemError(err))
+            }
+        }
+    }
+}
+
+/**## ODLanguage `class`
+ * This is an Open Discord language file.
+ * 
+ * It contains metadata and all translation strings available in this language.
+ * Register this class to an `ODLanguageManager` to use it!
+ * 
+ * JSON languages should be created using the `ODJsonLanguage` class instead!
+ */
+export class ODLanguage extends ODManagerData {
+    /**The name of the file with extension. */
+    file: string = ""
+    /**The path to the file relative to the main directory. */
+    path: string = ""
+    /**The raw object data of the translation. */
+    data: any
+    /**The metadata of the language if available. */
+    metadata: ODLanguageMetadata|null = null
+
+    constructor(id:ODValidId, data:any){
+        super(id)
+        this.data = data
+    }
+
+    /**Init the language. */
+    init(): ODPromiseVoid {
+        //nothing
+    }
+}
+
+/**## ODJsonLanguage `class`
+ * This is an Open Discord JSON language file.
+ * 
+ * It contains metadata and all translation strings from a certain JSON file (in `./languages/`).
+ * Register this class to an `ODLanguageManager` to use it!
+ * 
+ * Use the `ODLanguage` class to use translations from non-JSON files!
+ */
+export class ODJsonLanguage extends ODLanguage {
+    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("./languages/",this.file)
+    }
+
+    /**Init the langauge. */
+    init(): ODPromiseVoid {
+        if (!fs.existsSync(this.path)) throw new ODSystemError("Unable to parse language \""+nodepath.join("./",this.path)+"\", the file doesn't exist!")
+        try{
+            this.data = JSON.parse(fs.readFileSync(this.path).toString())
+        }catch(err){
+            process.emit("uncaughtException",err)
+            throw new ODSystemError("Unable to parse language \""+nodepath.join("./",this.path)+"\"!")
+        }
+        if (this.data["_TRANSLATION"]) this.metadata = this.data["_TRANSLATION"]
+    }
+}