chz-telegram-bot 0.3.14 → 0.3.16

package/dtos/chatInfo.ts

@@ -1,11 +1,12 @@
-export class ChatInfo {
-    /** Id of a chat that action is executed in. */
-    readonly id: number;
-    /** Name of a chat that action is executed in. */
-    readonly name: string;
+import { IncomingMessage } from './incomingMessage';
 
-    constructor(chatId: number, chatName: string) {
-        this.id = chatId;
-        this.name = chatName;
-    }
+export class ChatInfo {
+    constructor(
+        /** Id of a chat that action is executed in. */
+        readonly id: number,
+        /** Name of a chat that action is executed in. */
+        readonly name: string,
+        /** Last 100 messages in chat where action is executed */
+        readonly messageHistory: IncomingMessage[]
+    ) {}
 }

package/dtos/commandTriggerCheckResult.ts

@@ -20,22 +20,12 @@ export class CommandTriggerCheckResult {
         return new CommandTriggerCheckResult(true, [], false);
     }
 
-    readonly shouldExecute: boolean;
-    readonly matchResults: RegExpExecArray[];
-    readonly skipCooldown: boolean;
-    readonly reason: SkipTriggerReasons | undefined;
-
     constructor(
-        shouldExecute: boolean,
-        matchResults: RegExpExecArray[],
-        skipCooldown: boolean,
-        reason?: SkipTriggerReasons
-    ) {
-        this.shouldExecute = shouldExecute;
-        this.matchResults = matchResults;
-        this.skipCooldown = skipCooldown;
-        this.reason = reason;
-    }
+        readonly shouldExecute: boolean,
+        readonly matchResults: RegExpExecArray[],
+        readonly skipCooldown: boolean,
+        readonly reason?: SkipTriggerReasons
+    ) {}
 
     mergeWith(other: CommandTriggerCheckResult) {
         return new CommandTriggerCheckResult(

package/dtos/cooldownInfo.ts

@@ -1,5 +1,10 @@
 import { Seconds } from '../types/timeValues';
 
 export class CooldownInfo {
-    constructor(public seconds: Seconds, public message: string | undefined) {}
+    constructor(
+        /** New one-time cooldown in seconds */
+        readonly seconds: Seconds,
+        /** Cooldown message to be shown */
+        readonly message: string | undefined
+    ) {}
 }

package/dtos/incomingMessage.ts

@@ -40,7 +40,11 @@ export class IncomingMessage {
         return MessageType.Unknown;
     }
 
-    constructor(ctxMessage: TelegrafContextMessage, botName: string) {
+    constructor(
+        ctxMessage: TelegrafContextMessage,
+        botName: string,
+        history: IncomingMessage[]
+    ) {
         this.traceId = createTrace(
             this,
             botName,
@@ -62,7 +66,8 @@ export class IncomingMessage {
             ctxMessage.chat.id,
             'title' in ctxMessage.chat
                 ? `${ctxMessage.chat.title} ${ctxMessage.chat.id}`
-                : 'DM'
+                : 'DM',
+            history
         );
         this.type = this.detectMessageType(ctxMessage);
         this.updateObject = ctxMessage;

package/dtos/incomingQuery.ts

@@ -1,22 +1,14 @@
 import { TraceId } from '../types/trace';
 
 export class IncomingInlineQuery {
-    readonly queryId: string;
-    readonly query: string;
-    readonly userId: number;
-    readonly traceId: TraceId;
     readonly abortController: AbortController;
 
     constructor(
-        queryId: string,
-        query: string,
-        userId: number,
-        traceId: TraceId
+        readonly queryId: string,
+        readonly query: string,
+        readonly userId: number,
+        readonly traceId: TraceId
     ) {
-        this.queryId = queryId;
-        this.query = query;
-        this.userId = userId;
-        this.traceId = traceId;
         this.abortController = new AbortController();
     }
 }

package/dtos/messageInfo.ts

@@ -0,0 +1,17 @@
+import {
+    MessageTypeValue,
+    TelegrafContextMessage
+} from '../types/messageTypes';
+
+export class MessageInfo {
+    constructor(
+        /** Id of a message that triggered this action. */
+        readonly id: number,
+        /** Text of a message that triggered this action. */
+        readonly text: string,
+        /** Type of message being received */
+        readonly type: MessageTypeValue,
+        /** Message object recieved from Telegram */
+        readonly telegramUpdateObject: TelegrafContextMessage
+    ) {}
+}

package/dtos/userInfo.ts

@@ -0,0 +1,8 @@
+export class UserInfo {
+    constructor(
+        /** Id of a user that sent a message that triggered this action. */
+        readonly id: number,
+        /** Name of a user that sent a message that triggered this action. */
+        readonly name: string
+    ) {}
+}

package/entities/actions/commandAction.ts

@@ -6,7 +6,7 @@ import { toArray } from '../../helpers/toArray';
 import { IActionState } from '../../types/actionState';
 import { IActionWithState, ActionKey } from '../../types/action';
 import { CommandTriggerCheckResult } from '../../dtos/commandTriggerCheckResult';
-import { MessageContext } from '../context/messageContext';
+import { MessageContextInternal } from '../context/messageContext';
 import { CommandTrigger } from '../../types/commandTrigger';
 import { Noop } from '../../helpers/noop';
 import { MessageType } from '../../types/messageTypes';
@@ -66,7 +66,7 @@ export class CommandAction<TActionState extends IActionState>
         this.key = `command:${this.name.replace('.', '-')}` as ActionKey;
     }
 
-    async exec(ctx: MessageContext<TActionState>) {
+    async exec(ctx: MessageContextInternal<TActionState>) {
         if (!ctx.isInitialized)
             throw new Error(
                 `Context for ${this.key} is not initialized or already consumed`
@@ -108,7 +108,7 @@ export class CommandAction<TActionState extends IActionState>
                             ctx.chatInfo,
                             ctx.traceId,
                             this,
-                            new ReplyInfo(ctx.messageId)
+                            new ReplyInfo(ctx.messageInfo.id)
                         )
                     ];
 
@@ -145,7 +145,7 @@ export class CommandAction<TActionState extends IActionState>
     }
 
     private checkIfShouldBeExecuted(
-        ctx: MessageContext<TActionState>,
+        ctx: MessageContextInternal<TActionState>,
         trigger: CommandTrigger,
         state: TActionState
     ) {
@@ -153,14 +153,14 @@ export class CommandAction<TActionState extends IActionState>
 
         if (!triggerCheckResult.shouldExecute) return triggerCheckResult;
 
-        if (!ctx.fromUserId)
+        if (!ctx.userInfo.id)
             return CommandTriggerCheckResult.DontTriggerAndSkipCooldown(
                 'UserIdMissing'
             );
 
         const isUserAllowed =
             this.allowedUsers.length == 0 ||
-            this.allowedUsers.includes(ctx.fromUserId);
+            this.allowedUsers.includes(ctx.userInfo.id);
 
         if (!isUserAllowed)
             return CommandTriggerCheckResult.DontTriggerAndSkipCooldown(
@@ -187,14 +187,14 @@ export class CommandAction<TActionState extends IActionState>
     }
 
     private checkTrigger(
-        ctx: MessageContext<TActionState>,
+        ctx: MessageContextInternal<TActionState>,
         trigger: CommandTrigger
     ) {
-        if (trigger == MessageType.Any || trigger == ctx.messageType)
+        if (trigger == MessageType.Any || trigger == ctx.messageInfo.type)
             return CommandTriggerCheckResult.Trigger();
 
         if (typeof trigger == 'string')
-            return ctx.messageText.toLowerCase() == trigger.toLowerCase()
+            return ctx.messageInfo.text.toLowerCase() == trigger.toLowerCase()
                 ? CommandTriggerCheckResult.Trigger()
                 : CommandTriggerCheckResult.DoNotTrigger('TriggerNotSatisfied');
 
@@ -202,14 +202,14 @@ export class CommandAction<TActionState extends IActionState>
 
         trigger.lastIndex = 0;
 
-        const execResult = trigger.exec(ctx.messageText);
+        const execResult = trigger.exec(ctx.messageInfo.text);
         if (execResult != null) {
             let regexMatchLimit = 100;
             matchResults.push(execResult);
 
             if (trigger.global) {
                 while (regexMatchLimit > 0) {
-                    const nextResult = trigger.exec(ctx.messageText);
+                    const nextResult = trigger.exec(ctx.messageInfo.text);
 
                     if (nextResult == null) break;
 

package/entities/actions/inlineQueryAction.ts

@@ -1,6 +1,6 @@
 import { Noop } from '../../helpers/noop';
 import { ActionKey, IAction } from '../../types/action';
-import { InlineQueryContext } from '../context/inlineQueryContext';
+import { InlineQueryContextInternal } from '../context/inlineQueryContext';
 import { InlineQueryHandler } from '../../types/handlers';
 
 export class InlineQueryAction implements IAction {
@@ -24,7 +24,7 @@ export class InlineQueryAction implements IAction {
         this.key = `inline:${this.name.replace('.', '-')}` as ActionKey;
     }
 
-    async exec(ctx: InlineQueryContext) {
+    async exec(ctx: InlineQueryContextInternal) {
         if (!ctx.isInitialized)
             throw new Error(
                 `Context for ${this.key} is not initialized or already consumed`

package/entities/actions/replyCaptureAction.ts

@@ -3,7 +3,7 @@ import { Noop } from '../../helpers/noop';
 import { IActionState } from '../../types/actionState';
 import { CommandTrigger } from '../../types/commandTrigger';
 import { ActionKey, IAction, IActionWithState } from '../../types/action';
-import { ReplyContext } from '../context/replyContext';
+import { ReplyContextInternal } from '../context/replyContext';
 
 export class ReplyCaptureAction<TParentActionState extends IActionState>
     implements IAction
@@ -11,7 +11,7 @@ export class ReplyCaptureAction<TParentActionState extends IActionState>
     readonly parentMessageId: number;
     readonly key: ActionKey;
     readonly handler: (
-        replyContext: ReplyContext<TParentActionState>
+        replyContext: ReplyContextInternal<TParentActionState>
     ) => Promise<void>;
     readonly triggers: CommandTrigger[];
     readonly abortController: AbortController;
@@ -20,7 +20,7 @@ export class ReplyCaptureAction<TParentActionState extends IActionState>
         parentMessageId: number,
         parentAction: IActionWithState<TParentActionState>,
         handler: (
-            replyContext: ReplyContext<TParentActionState>
+            replyContext: ReplyContextInternal<TParentActionState>
         ) => Promise<void>,
         triggers: CommandTrigger[],
         abortController: AbortController
@@ -35,7 +35,7 @@ export class ReplyCaptureAction<TParentActionState extends IActionState>
             .replace('.', '')}` as ActionKey;
     }
 
-    async exec(ctx: ReplyContext<TParentActionState>) {
+    async exec(ctx: ReplyContextInternal<TParentActionState>) {
         if (!ctx.isInitialized)
             throw new Error(
                 `Context for ${this.key} is not initialized or already consumed`
@@ -61,7 +61,7 @@ export class ReplyCaptureAction<TParentActionState extends IActionState>
     }
 
     private checkIfShouldBeExecuted(
-        ctx: ReplyContext<TParentActionState>,
+        ctx: ReplyContextInternal<TParentActionState>,
         trigger: CommandTrigger
     ) {
         if (ctx.replyMessageId != this.parentMessageId)
@@ -69,11 +69,11 @@ export class ReplyCaptureAction<TParentActionState extends IActionState>
                 'TriggerNotSatisfied'
             );
 
-        if (trigger == ctx.messageType)
+        if (trigger == ctx.messageInfo.type)
             return CommandTriggerCheckResult.Trigger();
 
         if (typeof trigger == 'string')
-            if (ctx.messageText.toLowerCase() == trigger.toLowerCase())
+            if (ctx.messageInfo.text.toLowerCase() == trigger.toLowerCase())
                 return CommandTriggerCheckResult.Trigger();
             else
                 return CommandTriggerCheckResult.DoNotTrigger(
@@ -84,14 +84,14 @@ export class ReplyCaptureAction<TParentActionState extends IActionState>
 
         trigger.lastIndex = 0;
 
-        const execResult = trigger.exec(ctx.messageText);
+        const execResult = trigger.exec(ctx.messageInfo.text);
         if (execResult != null) {
             let regexMatchLimit = 100;
             matchResults.push(execResult);
 
             if (trigger.global) {
                 while (regexMatchLimit > 0) {
-                    const nextResult = trigger.exec(ctx.messageText);
+                    const nextResult = trigger.exec(ctx.messageInfo.text);
 
                     if (nextResult == null) break;
 

package/entities/actions/scheduledAction.ts

@@ -6,7 +6,7 @@ import { HoursOfDay } from '../../types/timeValues';
 import { IActionState } from '../../types/actionState';
 import { IActionWithState, ActionKey } from '../../types/action';
 import { CachedStateFactory } from '../cachedStateFactory';
-import { ChatContext } from '../context/chatContext';
+import { ChatContextInternal } from '../context/chatContext';
 import { Noop } from '../../helpers/noop';
 import { IScheduler } from '../../types/scheduler';
 import { getOrSetIfNotExists, getOrThrow } from '../../helpers/mapUtils';
@@ -46,7 +46,7 @@ export class ScheduledAction<TActionState extends IActionState>
         this.stateConstructor = stateConstructor;
     }
 
-    async exec(ctx: ChatContext<TActionState>) {
+    async exec(ctx: ChatContextInternal<TActionState>) {
         if (!ctx.isInitialized)
             throw new Error(
                 `Context for ${this.key} is not initialized or already consumed`

package/entities/context/baseContext.ts

@@ -7,7 +7,17 @@ import { IScheduler } from '../../types/scheduler';
 import { IStorageClient } from '../../types/storage';
 import { TraceId } from '../../types/trace';
 
-export abstract class BaseContext<TAction extends IAction> {
+export type BaseContextPropertiesToOmit =
+    | 'action'
+    | 'isInitialized'
+    | 'storage'
+    | 'scheduler'
+    | 'logger'
+    | 'responses'
+    | 'traceId'
+    | 'botName';
+
+export abstract class BaseContextInternal<TAction extends IAction> {
     isInitialized = false;
     private _responses: BotResponse[] = [];
 

package/entities/context/chatContext.ts

@@ -14,17 +14,28 @@ import { Milliseconds } from '../../types/timeValues';
 import { DelayResponse } from '../../dtos/responses/delay';
 import { ICaptureController } from '../../types/capture';
 import { CommandTrigger } from '../../types/commandTrigger';
-import { ReplyContext } from './replyContext';
-import { BaseContext } from './baseContext';
+import { ReplyContextInternal } from './replyContext';
+import {
+    BaseContextInternal,
+    BaseContextPropertiesToOmit
+} from './baseContext';
 import { ScheduledAction } from '../actions/scheduledAction';
 
+export type ChatContext<
+    TActionState extends IActionState,
+    TAction extends IActionWithState<TActionState> = ScheduledAction<TActionState>
+> = Omit<
+    ChatContextInternal<TActionState, TAction>,
+    BaseContextPropertiesToOmit
+>;
+
 /**
  * Context of action executed in chat.
  */
-export class ChatContext<
+export class ChatContextInternal<
     TActionState extends IActionState,
     TAction extends IActionWithState<TActionState> = ScheduledAction<TActionState>
-> extends BaseContext<TAction> {
+> extends BaseContextInternal<TAction> {
     protected createCaptureController(
         response: IReplyResponse
     ): ICaptureController {
@@ -32,7 +43,7 @@ export class ChatContext<
             captureReplies: (
                 trigger: CommandTrigger[],
                 handler: (
-                    replyContext: ReplyContext<TActionState>
+                    replyContext: ReplyContextInternal<TActionState>
                 ) => Promise<void>,
                 abortController: AbortController
             ) => {

package/entities/context/inlineQueryContext.ts

@@ -2,9 +2,17 @@ import { InlineQueryResult } from 'telegraf/types';
 import { BotResponse } from '../../types/response';
 import { InlineQueryAction } from '../actions/inlineQueryAction';
 import { InlineQueryResponse } from '../../dtos/responses/inlineQueryResponse';
-import { BaseContext } from './baseContext';
+import {
+    BaseContextInternal,
+    BaseContextPropertiesToOmit
+} from './baseContext';
 
-export class InlineQueryContext extends BaseContext<InlineQueryAction> {
+export type InlineQueryContext = Omit<
+    InlineQueryContextInternal,
+    BaseContextPropertiesToOmit | 'queryResults' | 'queryId'
+>;
+
+export class InlineQueryContextInternal extends BaseContextInternal<InlineQueryAction> {
     queryResults: InlineQueryResult[] = [];
     /**
      * Abort signal to be utilized in query handler.

package/entities/context/messageContext.ts

@@ -5,51 +5,46 @@ import { ImageMessage } from '../../dtos/responses/imageMessage';
 import { Reaction } from '../../dtos/responses/reaction';
 import { TextMessage } from '../../dtos/responses/textMessage';
 import { VideoMessage } from '../../dtos/responses/videoMessage';
-import { ChatContext } from './chatContext';
+import { ChatContextInternal } from './chatContext';
 import {
     MessageSendingOptions,
     TextMessageSendingOptions
 } from '../../types/messageSendingOptions';
-import {
-    MessageTypeValue,
-    TelegrafContextMessage
-} from '../../types/messageTypes';
 import { ReplyInfo } from '../../dtos/replyInfo';
 import { CommandAction } from '../actions/commandAction';
 import { Seconds } from '../../types/timeValues';
+import { BaseContextPropertiesToOmit } from './baseContext';
+import { MessageInfo } from '../../dtos/messageInfo';
+import { UserInfo } from '../../dtos/userInfo';
+
+export type MessageContext<TActionState extends IActionState> = Omit<
+    MessageContextInternal<TActionState>,
+    BaseContextPropertiesToOmit | 'startCooldown' | 'customCooldown'
+>;
 
 /**
  * Context of action executed in chat, in response to a message
  */
-export class MessageContext<
+export class MessageContextInternal<
     TActionState extends IActionState
-> extends ChatContext<TActionState, CommandAction<TActionState>> {
-    /** Id of a message that triggered this action. */
-    messageId!: number;
-    /** Text of a message that triggered this action. */
-    messageText!: string;
+> extends ChatContextInternal<TActionState, CommandAction<TActionState>> {
+    /** Information about the user that triggered this action */
+    userInfo!: UserInfo;
+    /** Information about the message that triggered this action */
+    messageInfo!: MessageInfo;
     /** Collection of Regexp match results on a message that triggered this action. Will be empty if trigger is not a Regexp. */
     matchResults: RegExpMatchArray[] = [];
-    /** Id of a user that sent a message that triggered this action. */
-    fromUserId: number | undefined;
     /** Indicates if cooldown should be started after action is executed. Set to `true` by default. */
     startCooldown: boolean = true;
-    /** Name of a user that sent a message that triggered this action. */
-    fromUserName!: string;
-    /** Type of message being received */
-    messageType!: MessageTypeValue;
-    /** Message object recieved from Telegram */
-    messageUpdateObject!: TelegrafContextMessage;
     /** Bot info from Telegram */
     botInfo!: UserFromGetMe;
-
     customCooldown: Seconds | undefined;
 
     private getQuotePart(quote: boolean | string) {
         return typeof quote == 'boolean'
             ? this.matchResults.length != 0
                 ? this.matchResults[0][1]
-                : this.messageText
+                : this.messageInfo.text
             : quote;
     }
 
@@ -65,7 +60,7 @@ export class MessageContext<
             this.chatInfo,
             this.traceId,
             this.action,
-            new ReplyInfo(this.messageId, quote ? quotedPart : undefined),
+            new ReplyInfo(this.messageInfo.id, quote ? quotedPart : undefined),
             options
         );
 
@@ -86,7 +81,7 @@ export class MessageContext<
             this.chatInfo,
             this.traceId,
             this.action,
-            new ReplyInfo(this.messageId, quote ? quotedPart : undefined),
+            new ReplyInfo(this.messageInfo.id, quote ? quotedPart : undefined),
             options
         );
 
@@ -107,7 +102,7 @@ export class MessageContext<
             this.chatInfo,
             this.traceId,
             this.action,
-            new ReplyInfo(this.messageId, quote ? quotedPart : undefined),
+            new ReplyInfo(this.messageInfo.id, quote ? quotedPart : undefined),
             options
         );
 
@@ -116,6 +111,10 @@ export class MessageContext<
         return this.createCaptureController(response);
     }
 
+    skipCooldown() {
+        this.startCooldown = false;
+    }
+
     startCustomCooldown(customCooldown: Seconds) {
         this.startCooldown = true;
         this.customCooldown = customCooldown;
@@ -202,7 +201,7 @@ export class MessageContext<
                 new Reaction(
                     this.traceId,
                     this.chatInfo,
-                    this.messageId,
+                    this.messageInfo.id,
                     emoji,
                     this.action
                 )

package/entities/context/replyContext.ts

@@ -9,33 +9,34 @@ import {
     TextMessageSendingOptions,
     MessageSendingOptions
 } from '../../types/messageSendingOptions';
-import {
-    MessageTypeValue,
-    TelegrafContextMessage
-} from '../../types/messageTypes';
 import { ReplyCaptureAction } from '../actions/replyCaptureAction';
 import { resolve } from 'path';
-import { BaseContext } from './baseContext';
-
-export class ReplyContext<
+import {
+    BaseContextInternal,
+    BaseContextPropertiesToOmit
+} from './baseContext';
+import { UserInfo } from '../../dtos/userInfo';
+import { MessageInfo } from '../../dtos/messageInfo';
+
+export type ReplyContext<TActionState extends IActionState> = Omit<
+    ReplyContextInternal<TActionState>,
+    | BaseContextPropertiesToOmit
+    | 'messageId'
+    | 'startCooldown'
+    | 'customCooldown'
+>;
+
+export class ReplyContextInternal<
     TParentActionState extends IActionState
-> extends BaseContext<ReplyCaptureAction<TParentActionState>> {
+> extends BaseContextInternal<ReplyCaptureAction<TParentActionState>> {
     /** Collection of Regexp match results on a message that triggered this action. Will be empty if trigger is not a Regexp. */
     matchResults!: RegExpExecArray[];
     /** Id of a message that triggered this action. */
     replyMessageId!: number | undefined;
-    /** Id of a message that triggered this action. */
-    messageId!: number;
-    /** Type of message being received */
-    messageType!: MessageTypeValue;
-    /** Text of a message that triggered this action. */
-    messageText!: string;
-    /** Id of a user that sent a message that triggered this action. */
-    fromUserId: number | undefined;
-    /** Name of a user that sent a message that triggered this action. */
-    fromUserName!: string;
-    /** Message object recieved from Telegram */
-    messageUpdateObject!: TelegrafContextMessage;
+    /** Information about the user that triggered this action */
+    userInfo!: UserInfo;
+    /** Information about the message that triggered this action */
+    messageInfo!: MessageInfo;
     /** Bot info from Telegram */
     botInfo!: UserFromGetMe;
 
@@ -45,7 +46,7 @@ export class ReplyContext<
         return typeof quote == 'boolean'
             ? this.matchResults.length != 0
                 ? this.matchResults[0][1]
-                : this.messageText
+                : this.messageInfo.text
             : quote;
     }
 
@@ -61,7 +62,7 @@ export class ReplyContext<
             this.chatInfo,
             this.traceId,
             this.action,
-            new ReplyInfo(this.messageId, quote ? quotedPart : undefined),
+            new ReplyInfo(this.messageInfo.id, quote ? quotedPart : undefined),
             options
         );
 
@@ -80,7 +81,7 @@ export class ReplyContext<
             this.chatInfo,
             this.traceId,
             this.action,
-            new ReplyInfo(this.messageId, quote ? quotedPart : undefined),
+            new ReplyInfo(this.messageInfo.id, quote ? quotedPart : undefined),
             options
         );
 
@@ -99,7 +100,7 @@ export class ReplyContext<
             this.chatInfo,
             this.traceId,
             this.action,
-            new ReplyInfo(this.messageId, quote ? quotedPart : undefined),
+            new ReplyInfo(this.messageInfo.id, quote ? quotedPart : undefined),
             options
         );
 
@@ -203,7 +204,7 @@ export class ReplyContext<
                 new Reaction(
                     this.traceId,
                     this.chatInfo,
-                    this.messageId,
+                    this.messageInfo.id,
                     emoji,
                     this.action
                 )

package/helpers/mapUtils.ts

@@ -1,4 +1,13 @@
-export function getOrSetIfNotExists<K, V>(map: Map<K, V>, key: K, fallback: V) {
+type KeyedReadonlyCollection<K, V> = { get: (key: K) => V | undefined };
+type KeyedWriteableCollection<K, V> = KeyedReadonlyCollection<K, V> & {
+    set: (key: K, value: V) => KeyedWriteableCollection<K, V>;
+};
+
+export function getOrSetIfNotExists<K, V>(
+    map: KeyedWriteableCollection<K, V>,
+    key: K,
+    fallback: V
+) {
     const existingValue = map.get(key);
     if (existingValue) return existingValue;
 
@@ -7,7 +16,11 @@ export function getOrSetIfNotExists<K, V>(map: Map<K, V>, key: K, fallback: V) {
     return fallback;
 }
 
-export function getOrThrow<K, V>(map: Map<K, V>, key: K, error: string) {
+export function getOrThrow<K, V>(
+    map: KeyedReadonlyCollection<K, V>,
+    key: K,
+    error: string = 'Key not found in collection'
+) {
     const existingValue = map.get(key);
     if (existingValue) return existingValue;