Matching text & content
A listener decorator picks the update type; a match predicate decides
whether this handler is the one for that update’s content. @OnMessage()
takes any message; @Hears(/^\d+$/) takes only the ones whose text is a number.
This page is the content layer: matching message text and callback data, ANDing
extra conditions onto a handler, and reading what a regex captured.
This is routing, not guarding. A predicate that returns false makes the
dispatcher try the next handler; a guard’s false rejects the update. Same
distinction the mental model draws — keep it in mind, it
decides where each check belongs.
| Decorator | Matches on | false means |
|---|---|---|
@Hears('hi') | message.text, exact | try the next handler |
@Hears(/^\d+$/) | message.text, regex .test() | try the next handler |
@Action('buy') / @Action(/…/) | callback_query.data | try the next handler |
@Match(pred) | a condition you write, ANDed in | try the next handler |
@Action and the callback route templates live on the callbacks
page; here we focus on @Hears, @Match, and reading captures.
Text with @Hears
@Hears reads message.text. A string matches it exactly; a RegExp is tested
against it. Nothing else about the message is inspected — a message with no text
(a photo, a sticker) never matches.
import { Router, Hears, Message } from 'nestgram';
@Router()
export class SupportRouter {
@Hears('ping')
ping(message: Message) {
return 'pong';
}
@Hears(/^\d+$/)
number(message: Message) {
return `That's a number: ${message.text}`;
}
}A subtle one worth naming: a g or y flag on your regex is stripped when
the predicate is built. Predicates are constructed once at boot and reused for
every update, and a global regex advances lastIndex between .test() calls —
so the same pattern would match, then miss, then match across successive
messages. Nestgram removes g/y so matching stays stateless. Write the flag
or don’t; the behavior is the same.
AND a condition with @Match
@Hears and @Action match on one field. When you need “this text and
this other condition”, reach for @Match. It ANDs one or more predicates into
every route the handler declares — across all its listener decorators at
once. A predicate is just an object with a matches(ctx) method returning a
boolean (sync or async): the same public RoutePredicate contract the built-ins
use, nothing privileged.
import {
Router,
Hears,
Match,
Message,
RoutePredicate,
TelegramExecutionContext,
} from 'nestgram';
const inPrivateChat: RoutePredicate = {
matches(ctx: TelegramExecutionContext) {
return ctx.chat?.type === 'private';
},
};
@Router()
export class DmNumberRouter {
@Hears(/^\d+$/)
@Match(inPrivateChat) // text is a number AND the chat is private
number(message: Message) {
return `Got ${message.text} in a DM.`;
}
}Where extra predicates passed to a single listener (@OnMessage(a, b)) narrow
that one route, @Match narrows the whole handler regardless of how many
update types it listens to — which is why it can sit over a handler that fans
out across types:
import {
Router,
OnMessage,
OnCallbackQuery,
Match,
Message,
CallbackQuery,
RoutePredicate,
} from 'nestgram';
const ADMIN_ID = 1234567;
const fromAdmin: RoutePredicate = {
matches: (ctx) => ctx.from?.id === ADMIN_ID,
};
@Router()
export class AdminRouter {
@OnMessage()
@OnCallbackQuery()
@Match(fromAdmin) // (message OR callback) AND fromAdmin
handle(event: Message | CallbackQuery) {
// ...
}
}Read regex captures
A regex @Hears (or @Action) doesn’t just match — it captures. Read the
groups instead of re-parsing the text by hand.
@Matches() injects the whole RegExpMatchArray from the regex route that
matched, so positional groups come back by index. The capture is run lazily —
the routing path stays a cheap boolean .test(), and the allocating .match()
fires only because a parameter actually reads it.
import { Router, Hears, Matches, Message } from 'nestgram';
@Router()
export class CalcRouter {
@Hears(/^add (\d+) (.+)$/)
add(message: Message, @Matches() match: RegExpMatchArray) {
return `Added ${match[1]}: ${match[2]}`;
}
}match[0] is the whole match, match[1..] the positional groups,
match.groups the named ones. Extraction runs against the regex of the route
that actually matched, so a sibling route the matcher only evaluated never
bleeds in. When the handler matched through a non-regex route — a string
@Hears, a @Command, a custom predicate — there’s no match to read, and
@Matches() resolves to undefined.
For a single named value, prefer @Param over indexing the array. Name the
group (?<amount>\d+) and it flows into @Param('amount') with a per-parameter
pipe — exactly like a @Command('add :amount') segment:
import { Router, Hears, Param, Message } from 'nestgram';
import { ParseIntPipe } from '@nestjs/common';
@Router()
export class CalcRouter {
@Hears(/^add (?<amount>\d+)$/)
add(message: Message, @Param('amount', ParseIntPipe) amount: number) {
return `Added ${amount}`;
}
}Because a @Command template segment and a regex named group feed the same
@Param, one handler can accept either spelling through a single parameter —
the slash command /add 5 or the plain text add 5:
import { Router, Command, Hears, Param, Message } from 'nestgram';
import { ParseIntPipe } from '@nestjs/common';
@Router()
export class CalcRouter {
@Command('add :amount')
@Hears(/^add (?<amount>\d+)$/)
add(message: Message, @Param('amount', ParseIntPipe) amount: number) {
return `Added ${amount}`;
}
}First match wins
Within a router, the boot-time route table is walked in method-declaration order, and the first handler whose predicate matches runs — the rest are never tried. Put specific handlers before catch-alls.
import { Router, Hears, OnMessage, Message } from 'nestgram';
@Router()
export class OrderRouter {
@Hears(/^\d+$/) // specific: checked first
number(message: Message) {
return `Number: ${message.text}`;
}
@OnMessage() // catch-all: only if nothing above matched
fallback(message: Message) {
return message.text;
}
}