chz-telegram-bot 0.0.23 → 0.0.25

package/helpers/builders/commandActionBuilder.ts

@@ -7,6 +7,9 @@ import { IActionState } from '../../types/actionState';
 import { toArray } from '../toArray';
 import { Noop } from '../noop';
 
+/**
+ * Builder for `CommandAction` with state represented by `TActionState`
+ */
 export class CommandActionBuilderWithState<TActionState extends IActionState> {
     name: string;
     trigger: string | RegExp | Array<string> | Array<RegExp> = [];
@@ -19,53 +22,82 @@ export class CommandActionBuilderWithState<TActionState extends IActionState> {
     handler: CommandHandler<TActionState> = Noop.call;
     condition: CommandCondition<TActionState> = Noop.true;
 
+    /**
+     * Builder for `CommandAction` with state represented by `TActionState`
+     * @param name Action name, will be used for logging and storage
+     * @param stateConstructor Function that creates default state object
+     */
     constructor(name: string, stateConstructor: () => TActionState) {
         this.name = name;
         this.stateConstructor = stateConstructor;
     }
 
+    /**
+     * Defines action trigger
+     * @param trigger If `string` or `string[]` is provided, will be triggered only on exact message match.
+     *
+     * If `RegExp` or `RegExp[]` is provided, will be triggered on successful match.
+     */
     on(trigger: string | RegExp | Array<string> | Array<RegExp>) {
         this.trigger = trigger;
 
         return this;
     }
 
+    /** Defines id (or ids) of users that are allowed to trigger this action.
+     * @param id User id or ids
+     */
     from(id: number | Array<number>) {
         this.allowedUsers = toArray(id);
 
         return this;
     }
 
+    /** Defines action logic itself, will be executed on trigger.
+     * @param handler Callback that will be called on trigger
+     */
     do(handler: CommandHandler<TActionState>) {
         this.handler = handler;
 
         return this;
     }
 
+    /** Defines condition that will be checked before trigger match check is executed.
+     * @param condition Condition check predicate
+     */
     when(condition: CommandCondition<TActionState>) {
         this.condition = condition;
 
         return this;
     }
 
+    /** If called during building, action is marked as disabled and never checked. */
     disabled() {
         this.active = false;
 
         return this;
     }
 
+    /** Sets action cooldown.
+     * @param seconds Cooldown in seconds.
+     */
     cooldown(seconds: Seconds) {
         this.cooldownSeconds = seconds;
 
         return this;
     }
 
+    /**
+     * Adds a chat to ignore list for this action.
+     * @param chatId Chat id to ignore.
+     */
     ignoreChat(chatId: number) {
         this.blacklist.push(chatId);
 
         return this;
     }
 
+    /** Builds action */
     build() {
         return new CommandAction(
             this.trigger,
@@ -81,7 +113,13 @@ export class CommandActionBuilderWithState<TActionState extends IActionState> {
     }
 }
 
+/**
+ * Builder for `CommandAction` with state represented by default state (containing only last execution date).
+ */
 export class CommandActionBuilder extends CommandActionBuilderWithState<ActionStateBase> {
+    /**
+     * Builder for `CommandAction` with state represented by default state (containing only last execution date).
+     */
     constructor(name: string) {
         super(name, () => new ActionStateBase());
     }

package/helpers/builders/scheduledActionBuilder.ts

@@ -6,6 +6,9 @@ import { ScheduledHandler } from '../../types/handlers';
 import { Hours, HoursOfDay } from '../../types/timeValues';
 import { Noop } from '../noop';
 
+/**
+ * Builder for `ScheduledAction` with state represented by `TActionState`
+ */
 export class ScheduledActionBuilderWithState<
     TActionState extends IActionState
 > {
@@ -18,29 +21,52 @@ export class ScheduledActionBuilderWithState<
 
     name: string;
 
+    /**
+     * Builder for `ScheduledAction` with state represented by `TActionState`
+     * @param name Action name, will be used for logging and storage
+     * @param stateConstructor Function that creates default state object
+     */
     constructor(name: string, stateConstructor: () => TActionState) {
         this.name = name;
         this.stateConstructor = stateConstructor;
     }
 
+    /**
+     * Adds a chat to whitelist for this action.
+     * @param chatId Chat id to execute in.
+     */
     allowIn(chatId: number) {
         this.whitelist.push(chatId);
 
         return this;
     }
 
+    /**
+     * Defines time for scheduled item execution.
+     * @param time Time of day (0 - 23) to execute action.
+     */
     runAt(time: HoursOfDay) {
         this.time = time;
 
         return this;
     }
 
+    /** Defines action logic itself, will be executed on timer.
+     * @param handler Callback that will be called on timer.
+     */
     do(handler: ScheduledHandler<TActionState>) {
         this.handler = handler;
 
         return this;
     }
 
+    /**
+     * Defines process-wide cache, that is shared by all actions of this type (even in different bot instances).
+     * Can be used for fetch request de-duping, etc.
+     * @param key Key that will be used to retrieve value from cache.
+     * @param itemFactory Callback that will be executed once to create cached value.
+     * @param invalidationTimeoutInHours Timeout for cache invalidation.
+     */
     withSharedCache(
         key: string,
         itemFactory: () => Promise<unknown>,
@@ -54,12 +80,14 @@ export class ScheduledActionBuilderWithState<
         return this;
     }
 
+    /** If called during building, action is marked as disabled and never checked. */
     disabled() {
         this.active = false;
 
         return this;
     }
 
+    /** Builds action */
     build() {
         return new ScheduledAction<TActionState>(
             this.name,
@@ -73,7 +101,13 @@ export class ScheduledActionBuilderWithState<
     }
 }
 
+/**
+ * Builder for `ScheduledAction` with state represented by default state (containing only last execution date).
+ */
 export class ScheduledActionBuilder extends ScheduledActionBuilderWithState<ActionStateBase> {
+    /**
+     * Builder for `ScheduledAction` with state represented by default state (containing only last execution date).
+     */
     constructor(name: string) {
         super(name, () => new ActionStateBase());
     }

package/helpers/reverseRecord.ts

@@ -0,0 +1,7 @@
+export function reverseRecord<T extends PropertyKey, U extends PropertyKey>(
+    input: Record<T, U>
+) {
+    return Object.fromEntries(
+        Object.entries(input).map(([key, value]) => [value, key])
+    ) as Record<U, T>;
+}

package/main.ts

@@ -13,13 +13,23 @@ function log(text: string) {
     Logger.logWithTraceId('ALL BOTS', 'System:Bot', 'System', text);
 }
 
+/**
+ * Starts bot
+ */
 async function startBot(options: {
+    /** Bot name, used in logging */
     name: string;
+    /** Path to file containing Telegram Bot token. */
     tokenFilePath: string;
+    /** Collection of actions that will be executed as a response to message from used. Created using `CommandActionBuilder`.*/
     commands: CommandAction<IActionState>[];
+    /** Collection of actions that will be executed on timer. Created using `ScheduledActionBuilder`.*/
     scheduled: ScheduledAction<IActionState>[];
-    chats: Map<string, number>;
+    /** Object containing chat name and chat id pairs. Used for logging and execution of scheduled action. */
+    chats: Record<string, number>;
+    /** Storage client for bot state storage. If not provided, default `JsonFileStorage` will be used. */
     storageClient?: IStorageClient;
+    /** Storage path for default `JsonFileStorage` client. Will be used only if `storageClient` is not provided. If not provided, default value of `./storage/` will be used.*/
     storagePath?: string;
 }) {
     const token = await readFile(options.tokenFilePath, 'utf8');
@@ -37,6 +47,9 @@ async function startBot(options: {
     return bot;
 }
 
+/**
+ * Terminates all scheduled tasks, closes storage connections and stops all bots.
+ */
 async function stopBots(reason: string) {
     log(`Recieved termination code: ${reason}`);
     Scheduler.stopAll();
@@ -44,7 +57,7 @@ async function stopBots(reason: string) {
 
     log('Stopping bots...');
     for (const bot of bots) {
-        bot.stop(reason);
+        await bot.stop(reason);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "chz-telegram-bot",
-    "version": "0.0.23",
+    "version": "0.0.25",
     "type": "module",
     "dependencies": {
         "async-sema": "^3.1.1",

package/services/taskScheduler.ts

@@ -1,6 +1,5 @@
 import { TaskRecord } from '../entities/taskRecord';
-import { secondsToMilliseconds } from '../helpers/timeConvertions';
-import { Milliseconds, Seconds } from '../types/timeValues';
+import { Milliseconds } from '../types/timeValues';
 import { Logger } from './logger';
 
 class TaskScheduler {
@@ -24,7 +23,7 @@ class TaskScheduler {
         const task = new TaskRecord(name, taskId, interval);
 
         if (executeRightAway) {
-            setTimeout(action, secondsToMilliseconds(1 as Seconds));
+            setImmediate(action);
         }
 
         Logger.logWithTraceId(

package/services/telegramApi.ts

@@ -1,7 +1,7 @@
 import { InputFile, Message } from 'telegraf/types';
 import { ChatContext } from '../entities/context/chatContext';
 import { MessageContext } from '../entities/context/messageContext';
-import { reverseMap } from '../helpers/reverseMap';
+import { reverseRecord } from '../helpers/reverseRecord';
 import { IStorageClient } from '../types/storage';
 import { Logger } from './logger';
 import { Reaction } from '../entities/responses/reaction';
@@ -14,6 +14,9 @@ import { ImageMessage } from '../entities/responses/imageMessage';
 import { Telegram } from 'telegraf/typings/telegram';
 import { setTimeout } from 'timers/promises';
 import { Milliseconds } from '../types/timeValues';
+import { ScheduledAction } from '../entities/actions/scheduledAction';
+import { IActionState } from '../types/actionState';
+import { CommandAction } from '../entities/actions/commandAction';
 
 export class TelegramApiService {
     isFlushing = false;
@@ -21,24 +24,26 @@ export class TelegramApiService {
 
     botName: string;
     telegram: Telegram;
-    chats: Map<number, string>;
+    chats: Record<number, string>;
     storage: IStorageClient;
 
     constructor(
         botName: string,
         telegram: Telegram,
         storage: IStorageClient,
-        chats: Map<string, number>
+        chats: Record<string, number>
     ) {
         this.telegram = telegram;
         this.botName = botName;
-        this.chats = reverseMap(chats);
+        this.chats = reverseRecord(chats);
         this.storage = storage;
     }
 
     async flushResponses() {
         if (this.isFlushing) return;
 
+        this.isFlushing = true;
+
         while (this.messageQueue.length) {
             const message = this.messageQueue.pop();
 
@@ -51,7 +56,7 @@ export class TelegramApiService {
                 Logger.errorWithTraceId(
                     this.botName,
                     message.traceId,
-                    this.chats.get(message.chatId)!,
+                    this.chats[message.chatId],
                     error,
                     message
                 );
@@ -169,18 +174,18 @@ export class TelegramApiService {
         } as IBotApiInteractions;
     }
 
-    createContextForMessage(
+    createContextForMessage<TActionState extends IActionState>(
         incomingMessage: IncomingMessage,
-        commandKey: string
+        command: CommandAction<TActionState>
     ) {
         const firstName = incomingMessage.from?.first_name ?? 'Unknown user';
         const lastName = incomingMessage.from?.last_name
             ? ` ${incomingMessage.from?.last_name}`
             : '';
 
-        return new MessageContext(
+        return new MessageContext<TActionState>(
             this.botName,
-            commandKey,
+            command.key,
             this.getInteractions(),
             incomingMessage.chat.id,
             incomingMessage.chatName,
@@ -193,14 +198,17 @@ export class TelegramApiService {
         );
     }
 
-    createContextForChat(chatId: number, scheduledKey: string) {
-        return new ChatContext(
+    createContextForChat<TActionState extends IActionState>(
+        chatId: number,
+        scheduledAction: ScheduledAction<TActionState>
+    ) {
+        return new ChatContext<TActionState>(
             this.botName,
-            scheduledKey,
+            scheduledAction.key,
             this.getInteractions(),
             chatId,
-            this.chats.get(chatId)!,
-            `Scheduled:${scheduledKey}:${chatId}`,
+            this.chats[chatId],
+            `Scheduled:${scheduledAction.key}:${chatId}`,
             this.storage
         );
     }

package/types/handlers.ts

@@ -4,12 +4,17 @@ import { IActionState } from './actionState';
 import { CachedValueAccessor } from './cachedValueAccessor';
 
 export type CommandHandler<TActionState extends IActionState> = (
+    /** Context of action executed in chat, in response to a message. */
     ctx: MessageContext<TActionState>,
+    /** State of an action being executed. */
     state: TActionState
 ) => Promise<void>;
 
 export type ScheduledHandler<TActionState extends IActionState> = (
-    ctx: ChatContext,
+    /** Context of action executed in chat. */
+    ctx: ChatContext<TActionState>,
+    /** Function that will attempt to get value from cache. If there is no value found, corresponding cached state factory will be called. */
     getCached: CachedValueAccessor,
+    /** State of an action being executed. */
     state: TActionState
 ) => Promise<void>;

package/helpers/reverseMap.ts

@@ -1,3 +0,0 @@
-export function reverseMap<K, V>(map: Map<K, V>): Map<V, K> {
-    return new Map(Array.from(map, ([key, value]) => [value, key]));
-}