Nestgram v2.0
Docs/Routing

Custom predicates

@Command, @Hears and @Action aren’t special. Each one is a class implementing a public RoutePredicate, handed to a listener decorator. When the built-ins don’t cover the shape you need to route on, you write your own against the same contract — and it runs at exactly the stage the framework’s own predicates do.

Mental model
listener decorator→predicate at boot→matches(ctx) per update→next handler or run

The contract

A predicate answers one question: does this route apply to the current update? It reads the execution context and returns a boolean, sync or async.

route-predicate.ts
import type { TelegramExecutionContext } from 'nestgram';

// The contract, exported from 'nestgram' — you implement it on a class.
interface RoutePredicate {
  matches(ctx: TelegramExecutionContext): boolean | Promise<boolean>;
}

This is routing, not guarding. A false here tells the dispatcher to try the next handler; it doesn’t reject the update the way a guard’s false does. The predicates are instantiated once when DiscoveryService builds the boot-time route table, then reused for every update — so a predicate instance is shared, keep it stateless.

The context hands you several views of the same update:

AccessorWhat you get
ctx.updatethe raw Update Telegram sent, Readonly
ctx.kindthe resolved UpdateKind (resolveKind’s whitelist)
ctx.eventthe rich typed event (Message, CallbackQuery, …)
ctx.messagethe rich Message on a message update, else undefined
ctx.callbackQuerythe rich CallbackQuery on a callback update, else undefined
ctx.chatthe Chat the update happened in, if any
ctx.fromthe User who triggered it, if any

ctx.event is built lazily and cached; reach for ctx.update when you only need a raw field and want to skip building the rich event. ctx.message and ctx.callbackQuery are that cached event narrowed to a concrete type — the rich way to read content in a predicate (ctx.message?.hasEntity('mention')), no raw update.message needed. For a less common kind, ctx.eventOf(InlineQuery) gives the same narrowing for any event class.

Writing one

Say you want a handler that only fires in private chats. Implement matches, read what you need off the context, return a boolean.

private-chat.predicate.ts
import { RoutePredicate, TelegramExecutionContext } from 'nestgram';

export class PrivateChatPredicate implements RoutePredicate {
  matches(ctx: TelegramExecutionContext): boolean {
    return ctx.chat?.type === 'private';
  }
}

You register it by passing an instance to a listener decorator. Extra predicates all have to pass — they compose as a logical AND, narrowing the route:

dm.router.ts
import { Router, OnMessage, Message } from 'nestgram';
import { PrivateChatPredicate } from './private-chat.predicate';

@Router()
export class DmRouter {
  @OnMessage(new PrivateChatPredicate())
  dmOnly(message: Message) {
    return 'This only runs in private chats.';
  }
}

Feeding @Param from a predicate

The built-in @Param('id') doesn’t read the route template directly — it asks the predicate that matched for its captured segments. A predicate opts into that by also implementing RouteParamSource: return a Record<string, string> of named segments, or null when this update didn’t match through it.

@Param('name') walks the matched handler’s predicates, calls extractParams, and reads the named key — so the same @Param you already use on @Command and @Action works against your predicate with no extra wiring.

locale-prefix.predicate.ts
import {
  RoutePredicate,
  RouteParamSource,
  TelegramExecutionContext,
} from 'nestgram';

// Matches a message like `en:reset` and exposes the `lang` segment to @Param.
export class LocalePrefixPredicate implements RoutePredicate, RouteParamSource {
  private static readonly PATTERN = /^(?<lang>[a-z]{2}):reset$/;

  matches(ctx: TelegramExecutionContext): boolean {
    return this.extractParams(ctx) !== null;
  }

  extractParams(ctx: TelegramExecutionContext): Record<string, string> | null {
    const text = ctx.update.message?.text;
    if (text === undefined) {
      return null;
    }

    return text.match(LocalePrefixPredicate.PATTERN)?.groups ?? null;
  }
}
locale.router.ts
import { Router, OnMessage, Param, Message } from 'nestgram';
import { LocalePrefixPredicate } from './locale-prefix.predicate';

@Router()
export class LocaleRouter {
  @OnMessage(new LocalePrefixPredicate())
  reset(message: Message, @Param('lang') lang: string) {
    return `Resetting locale to ${lang}.`;
  }
}

If your predicate captures with a regex and you’d rather take the whole RegExpMatchArray by index than name every group, implement RegexMatchSource instead — extractMatch(ctx) returns the array (or null), and @Matches() injects it. Named groups on that array still surface through @Param. This is exactly how a regex @Hears(/add (\d+)/) feeds both @Matches() and @Param('amount').

Implement……to inject viaYou return
RoutePredicate(routing only)boolean | Promise<boolean>
RouteParamSource@Param('id')Record<string, string> | null
RegexMatchSource@Matches()RegExpMatchArray | null