@grammyjs/commands 0.3.1 → 0.5.1

package/README.md

@@ -1,18 +1,18 @@
 ## grammY Commands Plugin
 
-This plugin provides a convenient way to define and manage commands for your grammY bot. It simplifies the process of setting up commands with scopes and localization.
+This plugin provides a convenient way to define and manage commands for your grammY bot. It simplifies the process of
+setting up commands with scopes and localization.
 
 ## Installation
 
-
 ```sh
 npm i @grammyjs/commands
 ```
 
 ## Usage
 
-The main functionality of this plugin is to define your commands, localize them, and give them handlers for each [scope](https://core.telegram.org/bots/api#botcommandscope), like so:
-
+The main functionality of this plugin is to define your commands, localize them, and give them handlers for each
+[scope](https://core.telegram.org/bots/api#botcommandscope), like so:
 
 ```typescript
 import { Bot } from "grammy";
@@ -23,9 +23,15 @@ const bot = new Bot("<telegram token>");
 const myCommands = new Commands();
 
 myCommands.command("start", "Initializes bot configuration")
-  .localize("pt", "start", "Inicializa as configurações do bot")
-  .addToScope({ type: "all_private_chats" }, (ctx) => ctx.reply(`Hello, ${ctx.chat.first_name}!`))
-  .addToScope({ type: "all_group_chats" }, (ctx) => ctx.reply(`Hello, members of ${ctx.chat.title}!`));
+    .localize("pt", "start", "Inicializa as configurações do bot")
+    .addToScope(
+        { type: "all_private_chats" },
+        (ctx) => ctx.reply(`Hello, ${ctx.chat.first_name}!`),
+    )
+    .addToScope(
+        { type: "all_group_chats" },
+        (ctx) => ctx.reply(`Hello, members of ${ctx.chat.title}!`),
+    );
 
 // Calls `setMyCommands`
 await myCommands.setCommands(bot);
@@ -36,17 +42,17 @@ bot.use(myCommands);
 bot.start();
 ```
 
-It is very important that you call `bot.use` with your instance of the `Commands` class.
-Otherwise, the command handlers will not be registered, and your bot will not respond to those commands.
+It is very important that you call `bot.use` with your instance of the `Commands` class. Otherwise, the command handlers
+will not be registered, and your bot will not respond to those commands.
 
 ### Context shortcuts
 
-This plugin provides a shortcut for setting the commands for the current chat.
-To use it, you need to install the commands flavor and the plugin itself, like so:
+This plugin provides a shortcut for setting the commands for the current chat. To use it, you need to install the
+commands flavor and the plugin itself, like so:
 
 ```typescript
 import { Bot, Context } from "grammy";
-import { Commands, CommandsFlavor, commands } from "@grammyjs/commands";
+import { Commands, commands, CommandsFlavor } from "@grammyjs/commands";
 
 type BotContext = CommandsFlavor;
 
@@ -54,15 +60,15 @@ const bot = new Bot<BotContext>("<telegram_token>");
 bot.use(commands());
 
 bot.on("message", async (ctx) => {
-  const cmds = new Commands();
+    const cmds = new Commands();
 
-  cmds.command("start", "Initializes bot configuration")
-    .localize("pt", "start", "Inicializa as configurações do bot");
+    cmds.command("start", "Initializes bot configuration")
+        .localize("pt", "start", "Inicializa as configurações do bot");
 
-  await ctx.setMyCommands(cmds);
+    await ctx.setMyCommands(cmds);
 
-  return ctx.reply("Commands set!");
+    return ctx.reply("Commands set!");
 });
 
-bot.start()
-```
+bot.start();
+```

package/out/command.d.ts

@@ -1,25 +1,125 @@
 import { type BotCommand, type BotCommandScope, type BotCommandScopeAllChatAdministrators, type BotCommandScopeAllGroupChats, type BotCommandScopeAllPrivateChats, type ChatTypeMiddleware, type Context, type Middleware, type MiddlewareObj } from "./deps.node.js";
+import { CommandOptions } from "./types.js";
 export type MaybeArray<T> = T | T[];
 type BotCommandGroupsScope = BotCommandScopeAllGroupChats | BotCommandScopeAllChatAdministrators;
+export declare const matchesPattern: (value: string, pattern: string | RegExp) => boolean;
+/**
+ * Class that represents a single command and allows you to configure it.
+ */
 export declare class Command<C extends Context = Context> implements MiddlewareObj<C> {
     private _scopes;
     private _languages;
     private _composer;
-    constructor(name: string, description: string);
+    private _options;
+    /**
+     * Constructor for the `Command` class.
+     * Do not call this directly. Instead, use the `command` method from the `Commands` class
+     *
+     * @param name Default command name
+     * @param description Default command description
+     * @param options Options object that shuold apply to this command only
+     * @access package
+     */
+    constructor(name: string | RegExp, description: string, options?: Partial<CommandOptions>);
+    /**
+     * Get registered scopes for this command
+     */
     get scopes(): BotCommandScope[];
+    /**
+     * Get registered languages for this command
+     */
     get languages(): Map<string, {
-        name: string;
+        name: string | RegExp;
         description: string;
     }>;
-    get names(): string[];
-    get name(): string;
+    /**
+     * Get registered names for this command
+     */
+    get names(): (string | RegExp)[];
+    /**
+     * Get the default name for this command
+     */
+    get name(): string | RegExp;
+    /**
+     * Get the default description for this command
+     */
     get description(): string;
-    addToScope(scope: BotCommandGroupsScope, ...middleware: ChatTypeMiddleware<C, "group" | "supergroup">[]): this;
-    addToScope(scope: BotCommandScopeAllPrivateChats, ...middleware: ChatTypeMiddleware<C, "private">[]): this;
-    addToScope(scope: BotCommandScope, ...middleware: Array<Middleware<C>>): this;
-    localize(languageCode: string, name: string, description: string): this;
-    getLocalizedName(languageCode: string): string;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const myCommands = new Commands();
+     * myCommands.command("start", "Initializes bot configuration")
+     *     .addToScope(
+     *         { type: "all_private_chats" },
+     *         (ctx) => ctx.reply(`Hello, ${ctx.chat.first_name}!`),
+     *     )
+     *     .addToScope(
+     *         { type: "all_group_chats" },
+     *         (ctx) => ctx.reply(`Hello, members of ${ctx.chat.title}!`),
+     *     );
+     * ```
+     *
+     * @param scope Which scope this command should be available on
+     * @param middleware The handler for this command on the specified scope
+     * @param options Additional options that should apply only to this scope
+     */
+    addToScope(scope: BotCommandGroupsScope, middleware: MaybeArray<ChatTypeMiddleware<C, "group" | "supergroup">>, options?: Partial<CommandOptions>): this;
+    addToScope(scope: BotCommandScopeAllPrivateChats, middleware: MaybeArray<ChatTypeMiddleware<C, "private">>, options?: Partial<CommandOptions>): this;
+    addToScope(scope: BotCommandScope, middleware: MaybeArray<Middleware<C>>, options?: Partial<CommandOptions>): this;
+    /**
+     * Creates a matcher for the given command that can be used in filtering operations
+     *
+     * @example
+     * ```ts
+     * bot
+     *  .filter(
+     *    Command.hasCommand(/\/delete_(.*)/),
+     *    (ctx) => ctx.reply(`Deleting ${ctx.message?.text?.split("_")[1]}`)
+     *  )
+     * ```
+     *
+     * @param command Command name or RegEx
+     * @param options Options that should apply to the matching algorithm
+     * @returns A predicate that matches the given command
+     */
+    static hasCommand(command: MaybeArray<string | RegExp>, options: CommandOptions): (ctx: Context) => boolean;
+    /**
+     * Adds a new translation for the command
+     *
+     * @example
+     * ```ts
+     * myCommands
+     *  .command("start", "Starts the bot configuration")
+     *  .localize("pt", "iniciar", "Inicia a configuração do bot")
+     * ```
+     *
+     * @param languageCode Language this translation applies to
+     * @param name Localized command name
+     * @param description Localized command description
+     */
+    localize(languageCode: string, name: string | RegExp, description: string): this;
+    /**
+     * Gets the localized command name of an existing translation
+     * @param languageCode Language to get the name for
+     * @returns Localized command name
+     */
+    getLocalizedName(languageCode: string): string | RegExp;
+    /**
+     * Gets the localized command name of an existing translation
+     * @param languageCode Language to get the name for
+     * @returns Localized command name
+     */
     getLocalizedDescription(languageCode: string): string;
+    /**
+     * Converts command to an object representation.
+     * Useful for JSON serialization.
+     *
+     * @param languageCode If specified, uses localized versions of the command name and description
+     * @returns Object representation of this command
+     */
     toObject(languageCode?: string): BotCommand;
     middleware(): import("grammy").MiddlewareFn<C>;
 }

package/out/command.js

@@ -1,58 +1,216 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Command = void 0;
+exports.Command = exports.matchesPattern = void 0;
 const deps_node_js_1 = require("./deps.node.js");
-const isAdmin = (ctx) => ctx.getAuthor().then((author) => ["administrator", "creator"].includes(author.status));
+const errors_js_1 = require("./errors.js");
+const ensureArray = (value) => Array.isArray(value) ? value : [value];
+const isAdmin = (ctx) => ctx
+    .getAuthor()
+    .then((author) => ["administrator", "creator"].includes(author.status));
+const matchesPattern = (value, pattern) => typeof pattern === "string" ? value === pattern : pattern.test(value);
+exports.matchesPattern = matchesPattern;
+/**
+ * Class that represents a single command and allows you to configure it.
+ */
 class Command {
-    constructor(name, description) {
+    /**
+     * Constructor for the `Command` class.
+     * Do not call this directly. Instead, use the `command` method from the `Commands` class
+     *
+     * @param name Default command name
+     * @param description Default command description
+     * @param options Options object that shuold apply to this command only
+     * @access package
+     */
+    constructor(name, description, options = {}) {
         this._scopes = [];
         this._languages = new Map();
         this._composer = new deps_node_js_1.Composer();
-        this._languages.set("default", { name, description });
+        this._options = {
+            prefix: "/",
+            matchOnlyAtStart: true,
+            targetedCommands: "optional",
+        };
+        this._options = { ...this._options, ...options };
+        if (this._options.prefix === "")
+            this._options.prefix = "/";
+        this._languages.set("default", { name: name, description });
     }
+    /**
+     * Get registered scopes for this command
+     */
     get scopes() {
         return this._scopes;
     }
+    /**
+     * Get registered languages for this command
+     */
     get languages() {
         return this._languages;
     }
+    /**
+     * Get registered names for this command
+     */
     get names() {
         return Array.from(this._languages.values()).map(({ name }) => name);
     }
+    /**
+     * Get the default name for this command
+     */
     get name() {
         return this._languages.get("default").name;
     }
+    /**
+     * Get the default description for this command
+     */
     get description() {
         return this._languages.get("default").description;
     }
-    addToScope(scope, ...middleware) {
-        (0, deps_node_js_1.match)(scope)
-            .with({ type: "default" }, () => this._composer.command(this.names, ...middleware))
-            .with({ type: "all_chat_administrators" }, () => this._composer.filter(isAdmin).command(this.names, ...middleware))
-            .with({ type: "all_private_chats" }, () => this._composer.chatType("private").command(this.names, ...middleware))
-            .with({ type: "all_group_chats" }, () => this._composer.chatType(["group", "supergroup"]).command(this.names, ...middleware))
-            .with({ type: deps_node_js_1.P.union("chat", "chat_administrators"), chat_id: deps_node_js_1.P.not(deps_node_js_1.P.nullish).select() }, (chatId) => this._composer.filter((ctx) => { var _a; return ((_a = ctx.chat) === null || _a === void 0 ? void 0 : _a.id) === chatId; }).filter(isAdmin).command(this.names, ...middleware))
-            .with({ type: "chat_member", chat_id: deps_node_js_1.P.not(deps_node_js_1.P.nullish).select("chatId"), user_id: deps_node_js_1.P.not(deps_node_js_1.P.nullish).select("userId") }, ({ chatId, userId }) => this._composer.filter((ctx) => { var _a; return ((_a = ctx.chat) === null || _a === void 0 ? void 0 : _a.id) === chatId; })
-            .filter((ctx) => { var _a; return ((_a = ctx.from) === null || _a === void 0 ? void 0 : _a.id) === userId; })
-            .command(this.names, ...middleware));
+    addToScope(scope, middleware, options = this._options) {
+        const middlewareArray = ensureArray(middleware);
+        const optionsObject = { ...this._options, ...options };
+        switch (scope.type) {
+            case "default":
+                this._composer
+                    .filter(Command.hasCommand(this.names, optionsObject))
+                    .use(...middlewareArray);
+                break;
+            case "all_chat_administrators":
+                this._composer
+                    .filter(Command.hasCommand(this.names, optionsObject))
+                    .filter(isAdmin)
+                    .use(...middlewareArray);
+                break;
+            case "all_private_chats":
+                this._composer
+                    .filter(Command.hasCommand(this.names, optionsObject))
+                    .chatType("private")
+                    .use(...middlewareArray);
+                break;
+            case "all_group_chats":
+                this._composer
+                    .filter(Command.hasCommand(this.names, optionsObject))
+                    .chatType(["group", "supergroup"])
+                    .use(...middlewareArray);
+                break;
+            case "chat":
+            case "chat_administrators":
+                if (scope.chat_id) {
+                    this._composer
+                        .filter(Command.hasCommand(this.names, optionsObject))
+                        .filter((ctx) => { var _a; return ((_a = ctx.chat) === null || _a === void 0 ? void 0 : _a.id) === scope.chat_id; })
+                        .filter(isAdmin)
+                        .use(...middlewareArray);
+                }
+                break;
+            case "chat_member":
+                if (scope.chat_id && scope.user_id) {
+                    this._composer
+                        .filter(Command.hasCommand(this.names, optionsObject))
+                        .filter((ctx) => { var _a; return ((_a = ctx.chat) === null || _a === void 0 ? void 0 : _a.id) === scope.chat_id; })
+                        .filter((ctx) => { var _a; return ((_a = ctx.from) === null || _a === void 0 ? void 0 : _a.id) === scope.user_id; })
+                        .use(...middlewareArray);
+                }
+                break;
+            default:
+                throw new errors_js_1.InvalidScopeError(scope);
+        }
         this._scopes.push(scope);
         return this;
     }
+    /**
+     * Creates a matcher for the given command that can be used in filtering operations
+     *
+     * @example
+     * ```ts
+     * bot
+     *  .filter(
+     *    Command.hasCommand(/\/delete_(.*)/),
+     *    (ctx) => ctx.reply(`Deleting ${ctx.message?.text?.split("_")[1]}`)
+     *  )
+     * ```
+     *
+     * @param command Command name or RegEx
+     * @param options Options that should apply to the matching algorithm
+     * @returns A predicate that matches the given command
+     */
+    static hasCommand(command, options) {
+        const { matchOnlyAtStart, prefix, targetedCommands } = options;
+        return (ctx) => {
+            if (!ctx.has(":text"))
+                return false;
+            if (matchOnlyAtStart && !ctx.msg.text.startsWith(prefix)) {
+                return false;
+            }
+            const commandNames = ensureArray(command);
+            const commands = prefix === "/"
+                ? ctx.entities("bot_command")
+                : ctx.msg.text.split(prefix).map((text) => ({ text }));
+            for (const { text } of commands) {
+                const [command, username] = text.split("@");
+                if (targetedCommands === "ignored" && username)
+                    continue;
+                if (targetedCommands === "required" && !username)
+                    continue;
+                if (username && username !== ctx.me.username)
+                    continue;
+                if (commandNames.some((name) => (0, exports.matchesPattern)(command.replace(prefix, ""), name))) {
+                    return true;
+                }
+            }
+            return false;
+        };
+    }
+    /**
+     * Adds a new translation for the command
+     *
+     * @example
+     * ```ts
+     * myCommands
+     *  .command("start", "Starts the bot configuration")
+     *  .localize("pt", "iniciar", "Inicia a configuração do bot")
+     * ```
+     *
+     * @param languageCode Language this translation applies to
+     * @param name Localized command name
+     * @param description Localized command description
+     */
     localize(languageCode, name, description) {
-        this._languages.set(languageCode, { name, description });
+        this._languages.set(languageCode, {
+            name: new RegExp(name),
+            description,
+        });
         return this;
     }
+    /**
+     * Gets the localized command name of an existing translation
+     * @param languageCode Language to get the name for
+     * @returns Localized command name
+     */
     getLocalizedName(languageCode) {
         var _a, _b;
         return (_b = (_a = this._languages.get(languageCode)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : this.name;
     }
+    /**
+     * Gets the localized command name of an existing translation
+     * @param languageCode Language to get the name for
+     * @returns Localized command name
+     */
     getLocalizedDescription(languageCode) {
         var _a, _b;
         return (_b = (_a = this._languages.get(languageCode)) === null || _a === void 0 ? void 0 : _a.description) !== null && _b !== void 0 ? _b : this.description;
     }
+    /**
+     * Converts command to an object representation.
+     * Useful for JSON serialization.
+     *
+     * @param languageCode If specified, uses localized versions of the command name and description
+     * @returns Object representation of this command
+     */
     toObject(languageCode = "default") {
+        const localizedName = this.getLocalizedName(languageCode);
         return {
-            command: this.getLocalizedName(languageCode),
+            command: localizedName instanceof RegExp ? "" : localizedName,
             description: this.getLocalizedDescription(languageCode),
         };
     }

package/out/commands.d.ts

@@ -0,0 +1,75 @@
+import { Command } from "./command.js";
+import { Api, BotCommand, BotCommandScope, Context } from "./deps.node.js";
+import { CommandOptions } from "./types.js";
+type SetMyCommandsParams = {
+    /**
+     * Scope
+     */
+    scope?: BotCommandScope;
+    language_code?: string;
+    commands: BotCommand[];
+};
+/**
+ * Central class that manages all registered commands.
+ * This is the starting point for the plugin, and this is what you should pass to `bot.use` so your commands get properly registered.
+ *
+ * @example
+ * ```typescript
+ * const myCommands = new Commands()
+ * commands.command("start", "start the bot configuration", (ctx) => ctx.reply("Hello there!"))
+ *
+ * // Registers the commands with the bot instance.
+ * bot.use(myCommands)
+ * ```
+ */
+export declare class Commands<C extends Context> {
+    private _languages;
+    private _scopes;
+    private _commands;
+    private _composer;
+    private _commandOptions;
+    constructor(options?: Partial<CommandOptions>);
+    private _addCommandToScope;
+    private _populateComposer;
+    private _populateMetadata;
+    /**
+     * Registers a new command and returns it.
+     * @param name Command name
+     * @param description Default command description
+     * @param options Extra options that should apply only to this command
+     * @returns An instance of the `Command` class
+     */
+    command(name: string | RegExp, description: string, options?: Partial<CommandOptions>): Command<C>;
+    /**
+     * Serializes the commands into multiple objects that can each be passed to a `setMyCommands` call.
+     *
+     * @returns One item for each combination of command + scope + language
+     */
+    toArgs(): SetMyCommandsParams[];
+    /**
+     * Serializes the commands of a single scope into objects that can each be passed to a `setMyCommands` call.
+     *
+     * @param scope Selected scope to be serialized
+     * @returns One item per command per language
+     */
+    toSingleScopeArgs(scope: BotCommandScope): SetMyCommandsParams[];
+    /**
+     * 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.
+     *
+     * @param Instance of `bot` or { api: bot.api }
+     */
+    setCommands({ api }: {
+        api: Api;
+    }): Promise<void>;
+    /**
+     * Alias for {@link toArgs}
+     */
+    toJSON(): SetMyCommandsParams[];
+    /**
+     * @returns A JSON serialized version of all the currently registered commands
+     */
+    toString(): string;
+    middleware(): import("grammy").MiddlewareFn<C>;
+}
+export {};

package/out/{plugin.js → commands.js}

@@ -3,13 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Commands = void 0;
 const command_js_1 = require("./command.js");
 const deps_node_js_1 = require("./deps.node.js");
+/**
+ * Central class that manages all registered commands.
+ * This is the starting point for the plugin, and this is what you should pass to `bot.use` so your commands get properly registered.
+ *
+ * @example
+ * ```typescript
+ * const myCommands = new Commands()
+ * commands.command("start", "start the bot configuration", (ctx) => ctx.reply("Hello there!"))
+ *
+ * // Registers the commands with the bot instance.
+ * bot.use(myCommands)
+ * ```
+ */
 class Commands {
-    constructor(commands = []) {
+    constructor(options = {}) {
         this._languages = new Set();
         this._scopes = new Map();
         this._commands = [];
         this._composer = new deps_node_js_1.Composer();
-        commands.forEach((command) => this._commands.push(command));
+        this._commandOptions = {};
+        this._commandOptions = options;
     }
     _addCommandToScope(scope, command) {
         var _a;
@@ -18,9 +32,7 @@ class Commands {
     }
     _populateComposer() {
         for (const command of this._commands) {
-            for (const args of command.languages.values()) {
-                this._composer.command(args.name, command.middleware());
-            }
+            this._composer.use(command.middleware());
         }
     }
     _populateMetadata() {
@@ -35,11 +47,23 @@ class Commands {
             }
         });
     }
-    command(name, description) {
-        const command = new command_js_1.Command(name, description);
+    /**
+     * Registers a new command and returns it.
+     * @param name Command name
+     * @param description Default command description
+     * @param options Extra options that should apply only to this command
+     * @returns An instance of the `Command` class
+     */
+    command(name, description, options = this._commandOptions) {
+        const command = new command_js_1.Command(name, description, options);
         this._commands.push(command);
         return command;
     }
+    /**
+     * Serializes the commands into multiple objects that can each be passed to a `setMyCommands` call.
+     *
+     * @returns One item for each combination of command + scope + language
+     */
     toArgs() {
         this._populateMetadata();
         const params = [];
@@ -47,13 +71,22 @@ class Commands {
             for (const language of this._languages) {
                 params.push({
                     scope: JSON.parse(scope),
-                    language_code: language === "default" ? undefined : language,
-                    commands: commands.map((command) => command.toObject(language)),
+                    language_code: language === "default"
+                        ? undefined
+                        : language,
+                    commands: commands.map((command) => command.toObject(language))
+                        .filter((args) => args.command.length > 0),
                 });
             }
         }
         return params.filter((params) => params.commands.length > 0);
     }
+    /**
+     * Serializes the commands of a single scope into objects that can each be passed to a `setMyCommands` call.
+     *
+     * @param scope Selected scope to be serialized
+     * @returns One item per command per language
+     */
     toSingleScopeArgs(scope) {
         this._populateMetadata();
         const params = [];
@@ -68,12 +101,24 @@ class Commands {
         }
         return params;
     }
+    /**
+     * 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.
+     *
+     * @param Instance of `bot` or { api: bot.api }
+     */
     async setCommands({ api }) {
         await Promise.all(this.toArgs().map((args) => api.raw.setMyCommands(args)));
     }
+    /**
+     * Alias for {@link toArgs}
+     */
     toJSON() {
         return this.toArgs();
     }
+    /**
+     * @returns A JSON serialized version of all the currently registered commands
+     */
     toString() {
         return JSON.stringify(this);
     }
@@ -81,9 +126,19 @@ class Commands {
         this._populateComposer();
         return this._composer.middleware();
     }
+    /**
+     * Replaces the `toString` method on node.js
+     *
+     * @see toString
+     */
     [Symbol.for("Deno.customInspect")]() {
         return this.toString();
     }
+    /**
+     * Replaces the `toString` method on Deno
+     *
+     * @see toString
+     */
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toString();
     }

package/out/context.d.ts

@@ -1,6 +1,7 @@
+import { Commands } from "./commands.js";
 import { Context, NextFunction } from "./deps.node.js";
-import { Commands } from "./plugin.js";
-export type CommandsFlavor<C extends Context = Context> = C & {
+import { JaroWinklerOptions } from "./jaro-winkler.js";
+export interface CommandsFlavor<C extends Context = Context> extends Context {
     /**
      * Sets the provided commands for the current chat.
      * Cannot be called on updates that don't have a `chat` property.
@@ -8,6 +9,18 @@ export type CommandsFlavor<C extends Context = Context> = C & {
      * @param commands List of available commands
      * @returns Promise with the result of the operations
      */
-    setMyCommands: (commands: Commands<C>) => Promise<true[]>;
-};
+    setMyCommands: (commands: Commands<C>) => Promise<void>;
+    /**
+     * Returns the nearest command to the user input.
+     * If no command is found, returns `null`.
+     *
+     * @param commands List of available commands
+     * @param options Options for the Jaro-Winkler algorithm
+     * @returns The nearest command or `null`
+     */
+    getNearestCommand: (commands: Commands<C>, options?: Partial<JaroWinklerOptions>) => string | null;
+}
+/**
+ * Installs the commands flavor into the context.
+ */
 export declare function commands<C extends Context>(): (ctx: CommandsFlavor<C>, next: NextFunction) => Promise<void>;

package/out/context.js

@@ -1,15 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commands = void 0;
+const jaro_winkler_js_1 = require("./jaro-winkler.js");
+/**
+ * Installs the commands flavor into the context.
+ */
 function commands() {
     return (ctx, next) => {
-        ctx.setMyCommands = (commands) => {
-            if (!ctx.chat)
+        ctx.setMyCommands = async (commands) => {
+            if (!ctx.chat) {
                 throw new Error("cannot call `ctx.setMyCommands` on an update with no `chat` property");
-            return Promise.all(commands
+            }
+            await Promise.all(commands
                 .toSingleScopeArgs({ type: "chat", chat_id: ctx.chat.id })
                 .map((args) => ctx.api.raw.setMyCommands(args)));
         };
+        ctx.getNearestCommand = (commands, options) => {
+            var _a;
+            if ((_a = ctx.msg) === null || _a === void 0 ? void 0 : _a.text) {
+                const userInput = ctx.msg.text.substring(1);
+                return (0, jaro_winkler_js_1.fuzzyMatch)(userInput, commands, { ...options });
+            }
+            return null;
+        };
         return next();
     };
 }

package/out/deps.node.d.ts

@@ -1,3 +1,2 @@
 export { Api, Bot, type ChatTypeContext, type ChatTypeMiddleware, type CommandMiddleware, Composer, Context, type Middleware, type MiddlewareObj, type NextFunction, } from "grammy";
 export type { BotCommand, BotCommandScope, BotCommandScopeAllChatAdministrators, BotCommandScopeAllGroupChats, BotCommandScopeAllPrivateChats, Chat, } from "grammy/types";
-export { match, P } from "ts-pattern";

package/out/deps.node.js

@@ -1,12 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.P = exports.match = exports.Context = exports.Composer = exports.Bot = exports.Api = void 0;
-// TODO: Replace with official deno module, once it arrives (https://github.com/gvergnaud/ts-pattern/pull/108)
+exports.Context = exports.Composer = exports.Bot = exports.Api = void 0;
 var grammy_1 = require("grammy");
 Object.defineProperty(exports, "Api", { enumerable: true, get: function () { return grammy_1.Api; } });
 Object.defineProperty(exports, "Bot", { enumerable: true, get: function () { return grammy_1.Bot; } });
 Object.defineProperty(exports, "Composer", { enumerable: true, get: function () { return grammy_1.Composer; } });
 Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return grammy_1.Context; } });
-var ts_pattern_1 = require("ts-pattern");
-Object.defineProperty(exports, "match", { enumerable: true, get: function () { return ts_pattern_1.match; } });
-Object.defineProperty(exports, "P", { enumerable: true, get: function () { return ts_pattern_1.P; } });

package/out/errors.d.ts

@@ -0,0 +1,4 @@
+import { BotCommandScope } from "./deps.node.js";
+export declare class InvalidScopeError extends Error {
+    constructor(scope: BotCommandScope);
+}

package/out/errors.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidScopeError = void 0;
+class InvalidScopeError extends Error {
+    constructor(scope) {
+        super(`Invalid scope: ${scope}`);
+        this.name = "InvalidScopeError";
+    }
+}
+exports.InvalidScopeError = InvalidScopeError;

package/out/jaro-winkler.d.ts

@@ -0,0 +1,9 @@
+import { Commands } from "./commands.js";
+import { Context } from "./deps.node.js";
+export declare function distance(s1: string, s2: string): number;
+export type JaroWinklerOptions = {
+    ignoreCase?: boolean;
+    similarityThreshold?: number;
+};
+export declare function JaroWinklerDistance(s1: string, s2: string, options: Partial<JaroWinklerOptions>): number;
+export declare function fuzzyMatch<C extends Context>(userInput: string, commands: Commands<C>, options: Partial<JaroWinklerOptions>): string | null;

package/out/jaro-winkler.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fuzzyMatch = exports.JaroWinklerDistance = exports.distance = void 0;
+function distance(s1, s2) {
+    if (s1.length === 0 || s2.length === 0) {
+        return 0;
+    }
+    const matchWindow = Math.floor(Math.max(s1.length, s2.length) / 2.0) - 1;
+    const matches1 = new Array(s1.length);
+    const matches2 = new Array(s2.length);
+    let m = 0; // number of matches
+    let t = 0; // number of transpositions
+    let i = 0; // index for string 1
+    let k = 0; // index for string 2
+    for (i = 0; i < s1.length; i++) {
+        // loop to find matched characters
+        const start = Math.max(0, i - matchWindow); // use the higher of the window diff
+        const end = Math.min(i + matchWindow + 1, s2.length); // use the min of the window and string 2 length
+        for (k = start; k < end; k++) {
+            // iterate second string index
+            if (matches2[k]) {
+                // if second string character already matched
+                continue;
+            }
+            if (s1[i] !== s2[k]) {
+                // characters don't match
+                continue;
+            }
+            // assume match if the above 2 checks don't continue
+            matches1[i] = true;
+            matches2[k] = true;
+            m++;
+            break;
+        }
+    }
+    // nothing matched
+    if (m === 0) {
+        return 0.0;
+    }
+    k = 0; // reset string 2 index
+    for (i = 0; i < s1.length; i++) {
+        // loop to find transpositions
+        if (!matches1[i]) {
+            // non-matching character
+            continue;
+        }
+        while (!matches2[k]) {
+            // move k index to the next match
+            k++;
+        }
+        if (s1[i] !== s2[k]) {
+            // if the characters don't match, increase transposition
+            // HtD: t is always less than the number of matches m, because transpositions are a subset of matches
+            t++;
+        }
+        k++; // iterate k index normally
+    }
+    // transpositions divided by 2
+    t /= 2.0;
+    return (m / s1.length + m / s2.length + (m - t) / m) / 3.0; // HtD: therefore, m - t > 0, and m - t < m
+    // HtD: => return value is between 0 and 1
+}
+exports.distance = distance;
+// Computes the Winkler distance between two string -- intrepreted from:
+// http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance
+// s1 is the first string to compare
+// s2 is the second string to compare
+// dj is the Jaro Distance (if you've already computed it), leave blank and the method handles it
+// ignoreCase: if true strings are first converted to lower case before comparison
+function JaroWinklerDistance(s1, s2, options) {
+    if (s1 === s2) {
+        return 1;
+    }
+    else {
+        if (options.ignoreCase) {
+            s1 = s1.toLowerCase();
+            s2 = s2.toLowerCase();
+        }
+        const jaro = distance(s1, s2);
+        const p = 0.1; // default scaling factor
+        let l = 0; // length of the matching prefix
+        while (s1[l] === s2[l] && l < 4) {
+            l++;
+        }
+        // HtD: 1 - jaro >= 0
+        return jaro + l * p * (1 - jaro);
+    }
+}
+exports.JaroWinklerDistance = JaroWinklerDistance;
+function fuzzyMatch(userInput, commands, options) {
+    const defaultSimilarityThreshold = 0.85;
+    const similarityThreshold = options.similarityThreshold ||
+        defaultSimilarityThreshold;
+    const commandsSet = new Set(commands
+        .toJSON()
+        .flatMap((item) => item.commands.map((command) => command.command)));
+    const bestMatch = Array.from(commandsSet).reduce((best, command) => {
+        const similarity = JaroWinklerDistance(userInput, command, {
+            ...options,
+        });
+        return similarity > best.similarity
+            ? { command, similarity }
+            : best;
+    }, { command: null, similarity: 0 });
+    return bestMatch.similarity > similarityThreshold
+        ? bestMatch.command
+        : null;
+}
+exports.fuzzyMatch = fuzzyMatch;

package/out/mod.d.ts

@@ -1,2 +1,3 @@
+export * from "./commands.js";
 export * from "./context.js";
-export * from "./plugin.js";
+export type { CommandOptions } from "./types.js";

package/out/mod.js

@@ -14,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./commands.js"), exports);
 __exportStar(require("./context.js"), exports);
-__exportStar(require("./plugin.js"), exports);

package/out/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Supported command options
+ */
+export interface CommandOptions {
+    /**
+     * The prefix used to identify a command.
+     * Defaults to `/`.
+     */
+    prefix: string;
+    /**
+     * Whether the command should only be matched at the start of the message.
+     * Defaults to `true`.
+     */
+    matchOnlyAtStart: boolean;
+    /**
+     * Whether to ignore or only care about commands ending with the bot's username.
+     * Defaults to `"optional"`.
+     *
+     * - `"ignored"`: only non-targeted commands are matched
+     * - `"optional"`: both targeted and non-targeted commands are matched
+     * - `"required"`: only targeted commands are matched
+     */
+    targetedCommands: "ignored" | "optional" | "required";
+}

package/out/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,27 +1,28 @@
 {
-  "name": "@grammyjs/commands",
-  "version": "0.3.1",
-  "description": "grammY Commands Plugin",
-  "main": "out/mod.js",
-  "scripts": {
-    "prepare": "deno task backport"
-  },
-  "keywords": [
-    "grammY",
-    "telegram",
-    "bot",
-    "commands"
-  ],
-  "author": "Roz <roz@rjmunhoz.me>",
-  "license": "MIT",
-  "dependencies": {
-    "grammy": "^1.17.1",
-    "ts-pattern": "^5.0.1"
-  },
-  "devDependencies": {
-    "typescript": "^5.1.6"
-  },
-  "files": [
-    "out"
-  ]
+    "name": "@grammyjs/commands",
+    "version": "0.5.1",
+    "description": "grammY Commands Plugin",
+    "main": "out/mod.js",
+    "scripts": {
+        "backport": "deno task backport",
+        "prepare": "deno task backport"
+    },
+    "keywords": [
+        "grammY",
+        "telegram",
+        "bot",
+        "commands"
+    ],
+    "author": "Roz <roz@rjmunhoz.me>",
+    "license": "MIT",
+    "dependencies": {
+        "grammy": "^1.17.1",
+        "ts-pattern": "^5.0.1"
+    },
+    "devDependencies": {
+        "typescript": "^5.1.6"
+    },
+    "files": [
+        "out"
+    ]
 }

package/out/plugin.d.ts

@@ -1,27 +0,0 @@
-import { Command } from "./command.js";
-import { Api, BotCommand, BotCommandScope, Context } from "./deps.node.js";
-type SetMyCommandsParams = {
-    scope?: BotCommandScope;
-    language_code?: string;
-    commands: BotCommand[];
-};
-export declare class Commands<C extends Context> {
-    private _languages;
-    private _scopes;
-    private _commands;
-    private _composer;
-    constructor(commands?: Command<C>[]);
-    private _addCommandToScope;
-    private _populateComposer;
-    private _populateMetadata;
-    command(name: string, description: string): Command<C>;
-    toArgs(): SetMyCommandsParams[];
-    toSingleScopeArgs(scope: BotCommandScope): SetMyCommandsParams[];
-    setCommands({ api }: {
-        api: Api;
-    }): Promise<void>;
-    toJSON(): SetMyCommandsParams[];
-    toString(): string;
-    middleware(): import("grammy").MiddlewareFn<C>;
-}
-export {};