chore: 0.8 release

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@grammyjs/commands",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "description": "grammY Commands Plugin",
     "main": "out/mod.js",
     "scripts": {
@@ -16,6 +16,7 @@
     "author": "Roz <[email protected]>",
     "license": "MIT",
     "dependencies": {
+        "@grammyjs/types": "^3.8.1",
         "grammy": "^1.17.1",
         "ts-pattern": "^5.0.1"
     },

src/command.ts

@@ -7,21 +7,18 @@ import {
     type ChatTypeMiddleware,
     Composer,
     type Context,
+    type LanguageCode,
     type Middleware,
     type MiddlewareObj,
 } from "./deps.deno.ts";
 import { InvalidScopeError } from "./errors.ts";
-import { CommandOptions } from "./types.ts";
-
-export type MaybeArray<T> = T | T[];
+import type { CommandOptions } from "./types.ts";
+import { ensureArray, type MaybeArray } from "./utils.ts";
 
 type BotCommandGroupsScope =
     | BotCommandScopeAllGroupChats
     | BotCommandScopeAllChatAdministrators;
 
-const ensureArray = <T>(value: MaybeArray<T>): T[] =>
-    Array.isArray(value) ? value : [value];
-
 const isAdmin = (ctx: Context) =>
     ctx
         .getAuthor()
@@ -36,7 +33,7 @@ export const matchesPattern = (value: string, pattern: string | RegExp) =>
 export class Command<C extends Context = Context> implements MiddlewareObj<C> {
     private _scopes: BotCommandScope[] = [];
     private _languages: Map<
-        string,
+        LanguageCode | "default",
         { name: string | RegExp; description: string }
     > = new Map();
     private _composer: Composer<C> = new Composer<C>();
@@ -100,6 +97,13 @@ export class Command<C extends Context = Context> implements MiddlewareObj<C> {
         return this._languages.get("default")!.description;
     }
 
+    /**
+     * Get the prefix for this command
+     */
+    get prefix() {
+        return this._options.prefix;
+    }
+
     /**
      * Registers the command to a scope to allow it to be handled and used with `setMyCommands`.
      * This will automatically apply filtering middlewares for you, so the handler only runs on the specified scope.
@@ -263,7 +267,7 @@ export class Command<C extends Context = Context> implements MiddlewareObj<C> {
      * @param description Localized command description
      */
     public localize(
-        languageCode: string,
+        languageCode: LanguageCode,
         name: string | RegExp,
         description: string,
     ) {
@@ -279,7 +283,7 @@ export class Command<C extends Context = Context> implements MiddlewareObj<C> {
      * @param languageCode Language to get the name for
      * @returns Localized command name
      */
-    public getLocalizedName(languageCode: string) {
+    public getLocalizedName(languageCode: LanguageCode | "default") {
         return this._languages.get(languageCode)?.name ?? this.name;
     }
 
@@ -288,7 +292,7 @@ export class Command<C extends Context = Context> implements MiddlewareObj<C> {
      * @param languageCode Language to get the name for
      * @returns Localized command name
      */
-    public getLocalizedDescription(languageCode: string) {
+    public getLocalizedDescription(languageCode: LanguageCode | "default") {
         return this._languages.get(languageCode)?.description ??
             this.description;
     }
@@ -300,7 +304,9 @@ export class Command<C extends Context = Context> implements MiddlewareObj<C> {
      * @param languageCode If specified, uses localized versions of the command name and description
      * @returns Object representation of this command
      */
-    public toObject(languageCode = "default"): BotCommand {
+    public toObject(
+        languageCode: LanguageCode | "default" = "default",
+    ): BotCommand {
         const localizedName = this.getLocalizedName(languageCode);
         return {
             command: localizedName instanceof RegExp

src/commands.ts

@@ -1,22 +1,29 @@
-import { Command, MaybeArray } from "./command.ts";
+import { Command } from "./command.ts";
 import {
     Api,
     BotCommand,
     BotCommandScope,
     CommandContext,
     Composer,
     Context,
+    type LanguageCode,
     Middleware,
 } from "./deps.deno.ts";
-import { CommandOptions } from "./types.ts";
+import type { CommandElementals, CommandOptions } from "./types.ts";
+import { type MaybeArray } from "./utils.ts";
 
+/**
+ * Interface for grouping {@link BotCommand}s that might (or not)
+ * be related to each other by scope and/or language.
+ */
 export type SetMyCommandsParams = {
-    /**
-     * Scope
-     * @param language_code two letter abbreviation in ISO_639 standard: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
-     */
+    /** If defined: scope on which the commands will take effect */
     scope?: BotCommandScope;
-    language_code?: string;
+    /** If defined: Language on which the commands will take effect.
+     * Two letter abbreviation in ISO_639 standard: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
+     */
+    language_code?: LanguageCode;
+    /** Commands that can be each one passed to a SetMyCommands Call */
     commands: BotCommand[];
 };
 
@@ -51,7 +58,7 @@ const isMiddleware = <C extends Context>(
  * ```
  */
 export class Commands<C extends Context> {
-    private _languages: Set<string> = new Set();
+    private _languages: Set<LanguageCode | "default"> = new Set();
     private _scopes: Map<string, Array<Command<C>>> = new Map();
     private _commands: Command<C>[] = [];
     private _composer: Composer<C> = new Composer();
@@ -150,10 +157,9 @@ export class Commands<C extends Context> {
                     language_code: language === "default"
                         ? undefined
                         : language,
-                    commands: commands.map((command) =>
-                        command.toObject(language)
-                    )
-                        .filter((args) => args.command.length > 0),
+                    commands: commands
+                        .filter((command) => typeof command.name === "string")
+                        .map((command) => command.toObject(language)),
                 });
             }
         }
@@ -187,6 +193,11 @@ export class Commands<C extends Context> {
      * Registers all commands to be displayed by clients according to their scopes and languages
      * Calls `setMyCommands` for each language of each scope of each command.
      *
+     * [!IMPORTANT]
+     * Calling this method with upperCased command names registered, will throw
+     * @see https://core.telegram.org/bots/api#botcommand
+     * @see https://core.telegram.org/method/bots.setBotCommands
+     *
      * @param Instance of `bot` or { api: bot.api }
      */
     public async setCommands({ api }: { api: Api }) {
@@ -196,10 +207,53 @@ export class Commands<C extends Context> {
     }
 
     /**
-     * Alias for {@link toArgs}
+     * Serialize all register commands into it's name, prefix and language
+     *
+     * @param filterLanguage if undefined, it returns all names
+     * else get only the locales for the given filterLanguage
+     * fallbacks to "default"
+     *
+     * @returns an array of {@link CommandElementals}
+     *
+     * Note: mainly used to serialize for {@link FuzzyMatch}
      */
-    public toJSON() {
-        return this.toArgs();
+
+    public toElementals(
+        filterLanguage?: LanguageCode | "default",
+    ): CommandElementals[] {
+        this._populateMetadata();
+
+        return Array.from(this._scopes.values())
+            .flat()
+            .flatMap(
+                (command) => {
+                    const elements = [];
+                    for (
+                        const [language, local] of command.languages.entries()
+                    ) {
+                        elements.push({
+                            name: local.name instanceof RegExp
+                                ? local.name.source
+                                : local.name,
+                            language,
+                            prefix: command.prefix,
+                            scopes: command.scopes,
+                            description: command.getLocalizedDescription(
+                                language,
+                            ),
+                        });
+                    }
+                    if (filterLanguage) {
+                        const filtered = elements.filter((command) =>
+                            command.language === filterLanguage
+                        );
+                        const defaulted = elements.filter((command) =>
+                            command.language === "default"
+                        );
+                        return filtered.length ? filtered[0] : defaulted[0];
+                    } else return elements;
+                },
+            );
     }
 
     /**