Class CommandReg

Класс, который берет на себя всю обязанность за регистрацию команд и шагов. Экземпляр не создаётся напрямую — он доступен как ctx.appContext.command в обработчиках и middleware.

Example

// Динамическая регистрация команды из middleware или обработчика
ctx.appContext.command.addCommand('dyn', ['динамика'], (cmd, ctrl) => {
    ctrl.text = 'Команда добавлена в рантайме';
});

Index

Constructors

constructor

new CommandReg(logger: ILogger, plugins: TAppPlugin): CommandReg
Конструктор класса CommandReg.
Parameters
- logger: ILogger
  Логгер для вывода предупреждений и ошибок
- plugins: TAppPlugin
  Плагины приложения (для получения кастомного RegExp)
Returns CommandReg
- Defined in core/utils/CommandReg.ts:374

Properties

commands

commands: Map<string, ICommandParam<BotController<IUserData, IPlatformData>>> = ...

Добавленные команды для обработки

commandsList

commandsList: [string, ICommandParam<BotController<IUserData, IPlatformData>>][] = []

Снимок команд для горячего цикла поиска.

Перебор Map через for...of аллоцирует пару-массив на каждой итерации — при скане тысяч команд это лишний мусор на каждый запрос. Снимок хранится обычным массивом пар и пересобирается лениво: мутации только помечают его флагом, пересборка происходит при первом поиске. Источник правды — commands (Map).

customCommandResolver

customCommandResolver: TCommandResolver | undefined

Кастомизация поиска команд.

regexpGroup

regexpGroup: Map<string, IGroupData> = ...

Сгруппированные регулярные выражения. Начинает отрабатывать как только было задано более 300 регулярных выражений

steps

steps: Map<string, IStepParam<BotController<IUserData, IPlatformData>>> = ...

Добавленные шаги для обработки

strictMode

strictMode: boolean = false

Флаг строгого режима работы приложения. В строгом режиме работы, все ReDoS регулярные выражения не будут добавляться.

Accessors

events

get events(): ReadonlyMap<
    TEventType,
    (
        (
            botController: BotController,
        ) => string | false | void | Promise<string | void>
    )[],
>
Зарегистрированные событийные обработчики (только чтение).

Readonly-аксессор над внутренним реестром: Map не пересоздаётся, чтение в горячем пути BotController.#eventResolver остаётся дешёвым. Мутации извне запрещены — только через addEvent/removeEvent/clearEvents.

Returns ReadonlyMap<
    TEventType,
    (
        (
            botController: BotController,
        ) => string | false | void | Promise<string | void>
    )[],
>
- Defined in core/utils/CommandReg.ts:1199

hasEvents

get hasEvents(): boolean
Флаг «есть хоть один событийный обработчик» (только чтение).

Обновляется методами регистрации/очистки; прямое присваивание извне невозможно, поэтому флаг не разъедется с реестром.

Returns boolean
- Defined in core/utils/CommandReg.ts:1209

Methods

addCommand

addCommand<
    TBotController extends
        BotController<IUserData, IPlatformData> = BotController<
        IUserData,
        IPlatformData,
    >,
>(
    commandName: string,
    slots: TSlots,
    cb: (
        userCommand: string,
        botController: TBotController,
    ) => string | void | Promise<string | void>,
    isPattern?: boolean,
): void
Добавляет команду для обработки пользовательских запросов

⚙️ Оптимизация: при регистрации более 300 команд с регулярными выражениями фреймворк автоматически объединяет их в группы для повышения производительности.
Type Parameters
- TBotController extends BotController<IUserData, IPlatformData> = BotController<IUserData, IPlatformData>
Parameters
- commandName: string
  Уникальный идентификатор команды
- slots: TSlots
  Триггеры для активации команды
  
  Если элемент — строка → ищется как подстрока (text.includes(...)).
  
  Если элемент — RegExp → проверяется как регулярное выражение (.test(text)).
  
  При isPattern = true строковые слоты компилируются в одно объединённое регулярное выражение с флагом ium.
  
  При isPattern = false каждый элемент обрабатывается по своему типу:
  
  string → как литерал (поиск подстроки),
  
  RegExp → как регулярное выражение
  
  Если ВСЕ слоты — готовые RegExp, isPattern для строк не применяется (строк нет) и команда трактуется как pattern. Без явного isPattern слоты склеиваются с их собственными (общими) флагами, а не с ium; слоты с разными флагами проверяются по отдельности.
- cb: (
  userCommand: string,
  botController: TBotController,
  ) => string | void | Promise<string | void>
  Функция-обработчик команды
- isPattern: boolean = false
  Использовать регулярные выражения (по умолчанию false)
Returns void
Example
Простая команда со словами:
```
commandReg.addCommand(
  'greeting',
  ['привет', 'здравствуй'],
  (cmd, ctrl) => {
    if (ctrl) ctrl.text = 'Здравствуйте!';
  }
);
```
Example
Команда с регулярными выражениями:
```
// Обработка чисел от 1 до 999
commandReg.addCommand(
  'number',
  ['\\b([1-9]|[1-9][0-9]|[1-9][0-9][0-9])\\b'],
  (cmd, ctrl) => {
    if (ctrl) ctrl.text = `Вы ввели число: ${cmd}`;
  },
  true  // включаем поддержку регулярных выражений
);
```
Example
Команда с доступом к состоянию:
```
commandReg.addCommand(
  'stats',
  ['статистика'],
  async (cmd, ctrl) => {
    if (ctrl) {
      // Доступ к пользовательским данным
      const visits = ctrl.userData?.visits || 0;
      ctrl.text = `Вы использовали приложение ${visits} раз`;

      // Доступ к кнопкам и другим UI элементам
      ctrl.buttons
        .addBtn('Сбросить статистику')
        .addBtn('Закрыть');
    }
  }
);
```
Remarks
Поиск команд оптимизирован:
1. Сначала проверяется точное совпадение
2. Если точного совпадения нет — выполняется последовательный перебор
При регистрации более 300 команд с регулярными выражениями фреймворк автоматически объединяет их в группы для повышения производительности.

При isPattern=true используются регулярные выражения JavaScript В callback доступен весь функционал BotController Можно использовать async функции в callback
- Defined in core/utils/CommandReg.ts:833

addEvent

addEvent<
    TBotController extends
        BotController<IUserData, IPlatformData> = BotController<
        IUserData,
        IPlatformData,
    >,
>(
    eventType: TEventType,
    cb: (
        botController: TBotController,
    ) => string | false | void | Promise<string | void>,
): this
Регистрирует обработчик универсального события платформы.

Обработчики событий вызываются до поиска шагов и команд. На одно событие можно зарегистрировать несколько обработчиков: они опрашиваются в порядке регистрации, пока один не вернёт строку-ответ (цепочка останавливается). Обработчик с false передаёт событие следующему обработчику; когда все отказались — запрос уходит в обычный конвейер (шаг → команда → интент → fallback).
Type Parameters
- TBotController extends BotController<IUserData, IPlatformData> = BotController<IUserData, IPlatformData>
Parameters
- eventType: TEventType
  Универсальный тип события ('photo', 'callback', …)
- cb: (
  botController: TBotController,
  ) => string | false | void | Promise<string | void>
  Функция-обработчик; может вернуть строку (текст ответа) или false (событие «не мой» — обработка продолжится по обычному конвейеру)
Returns this
- Defined in core/utils/CommandReg.ts:1227

addStep

addStep<
    TBotController extends
        BotController<IUserData, IPlatformData> = BotController<
        IUserData,
        IPlatformData,
    >,
>(
    stepName: string,
    handler: (
        botController: TBotController,
    ) => false | void | Promise<false | void>,
): this
Регистрирует обработчик для именованного шага диалога.

Шаг — это часть многошагового сценария (например: "регистрация", "оформление заказа"). После вызова ctx.thisIntentName = 'myStep' в команде или другом шаге, следующее сообщение пользователя будет обработано этим обработчиком.

💡 Обработчик получает полный BotController, как и в командах: доступны this.text, this.userData, this.buttons, this.thisIntentName и т.д.
Type Parameters
- TBotController extends BotController<IUserData, IPlatformData> = BotController<IUserData, IPlatformData>
Parameters
- stepName: string
  — Уникальное имя шага (например, 'enter_email').
- handler: (botController: TBotController) => false | void | Promise<false | void>
  — Функция, вызываемая при получении сообщения в этом шаге.
Returns this
Текущий экземпляр CommandReg.
Example
```
bot.addStep('confirm_age', (ctx) => {
  if (ctx.userCommand === 'да') {
    ctx.text = 'Отлично! Добро пожаловать.';
    ctx.thisIntentName = null; // завершаем сценарий
  } else {
    ctx.text = 'Извините, вход запрещён.';
    ctx.thisIntentName = 'goodbye'; // переходим к другому шагу
  }
});
```
- Defined in core/utils/CommandReg.ts:1138

clearCommands

clearCommands(): void
Удаляет все зарегистрированные команды

Returns void
- Defined in core/utils/CommandReg.ts:1097

clearEvents

clearEvents(): this
Удаляет все зарегистрированные событийные обработчики.

Returns this
Текущий экземпляр CommandReg
- Defined in core/utils/CommandReg.ts:1258

clearSteps

clearSteps(): this
Удаляет все зарегистрированные шаги.

⚠️ Это глобальная операция: все сценарии станут недоступны. Используйте с осторожностью (например, при перезагрузке логики приложения).

Returns this
Текущий экземпляр CommandReg.
- Defined in core/utils/CommandReg.ts:1171

getActualCommandsList

getActualCommandsList(): [
string,
ICommandParam<BotController<IUserData, IPlatformData>>,
][]
Возвращает актуальный снимок команд, пересобирая его при необходимости. Вызывается из горячего цикла поиска команд: при неизменном наборе команд (обычный прод-режим) стоимость — одна проверка булевого флага.

Returns [string, ICommandParam<BotController<IUserData, IPlatformData>>][]
- Defined in core/utils/CommandReg.ts:335

getCustomRegExp

getCustomRegExp(): RegExpConstructor | undefined
Возвращает конструктор RegExp (например, re2), заданный плагином regExp, для компиляции регулярных выражений. Если плагин не подключён — undefined.

Returns RegExpConstructor | undefined
- Defined in core/utils/CommandReg.ts:398

getExactMatchCommand

getExactMatchCommand(userCommand: string): string | undefined
Поиск команды по точному совпадению (без RegExp).
Parameters
- userCommand: string
  Команда пользователя (в нижнем регистре)
Returns string | undefined
Имя найденной команды или undefined
- Defined in core/utils/CommandReg.ts:386

isDangerRegex

isDangerRegex(slots: RegExp | TSlots): IDangerRegex
Проверяет, что переданное регулярное выражение не содержит уязвимых к ReDoS конструкций.

Если выражение признано небезопасным:
- В обычном режиме пишется сообщение (ошибка без re2, предупреждение с ним), и выражение используется как есть.
- В strictMode — пишется ошибка, и небезопасные слоты отбрасываются (status: false; для одиночного RegExp возвращаются пустые слоты, для массива — только безопасные слоты).
Parameters
- slots: RegExp | TSlots
  Слот(ы) или регулярное выражение для проверки.
Returns IDangerRegex
Исходные слоты (в обычном режиме) или безопасные слоты с флагом ошибки.
- Defined in core/utils/CommandReg.ts:457

removeCommand

removeCommand(commandName: string): void
Удаляет команду
Parameters
- commandName: string
  Имя команды
Returns void
- Defined in core/utils/CommandReg.ts:1064

removeEvent

removeEvent(eventType: TEventType): this
Удаляет все обработчики указанного события.
Parameters
- eventType: TEventType
  Тип события
Returns this
Текущий экземпляр CommandReg
- Defined in core/utils/CommandReg.ts:1247

removeStep

removeStep(stepName: string): this
Удаляет зарегистрированный шаг по имени.

После удаления шаг больше не будет обрабатываться, даже если активен у пользователя. (Рекомендуется завершать активные сценарии через ctx.thisIntentName = null перед удалением.)
Parameters
- stepName: string
  — Имя шага для удаления.
Returns this
Текущий экземпляр CommandReg.
- Defined in core/utils/CommandReg.ts:1158

setCommandGroupMode

setCommandGroupMode(mode: TCommandGroupMode): void
Устанавливает режим группировки регулярных выражений.
Parameters
- mode: TCommandGroupMode
  Режим группировки: 'auto', 'group' или 'no-group'
Returns void
- Defined in core/utils/CommandReg.ts:411

Class CommandReg

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns CommandReg

Properties

commands

commandsList

customCommandResolver

regexpGroup

steps

strictMode

Accessors

events

Returns ReadonlyMap< TEventType, ( ( botController: BotController, ) => string | false | void | Promise<string | void> )[],>

hasEvents

Returns boolean

Methods

addCommand

Type Parameters

Parameters

Returns void

Example

Example

Example

Remarks

addEvent

Type Parameters

Parameters

Returns this

addStep

Type Parameters

Parameters

Returns this

Example

clearCommands

Returns void

clearEvents

Returns this

clearSteps

Returns this

getActualCommandsList

Returns [string, ICommandParam<BotController<IUserData, IPlatformData>>][]

getCustomRegExp

Returns RegExpConstructor | undefined

getExactMatchCommand

Parameters

Returns string | undefined

isDangerRegex

Parameters

Returns IDangerRegex

removeCommand

Parameters

Returns void

removeEvent

Parameters

Returns this

removeStep

Parameters

Returns this

setCommandGroupMode

Parameters

Returns void

Settings

On This Page

Returns ReadonlyMap<
TEventType,
(
(
botController: BotController,
) => string | false | void | Promise<string | void>
)[],
>