@tgify/tgify 0.1.0 → 0.1.5

package/src/composer.ts

@@ -1,1008 +1,1008 @@
-/** @format */
-
-import * as tg from './core/types/typegram'
-import * as tt from './telegram-types'
-import { Middleware, MiddlewareFn, MiddlewareObj } from './middleware'
-import Context, { FilteredContext, NarrowedContext } from './context'
-import {
-  MaybeArray,
-  NonemptyReadonlyArray,
-  MaybePromise,
-  Guard,
-} from './core/helpers/util'
-import { type CallbackQuery } from './core/types/typegram'
-import { message, callbackQuery } from './filters'
-import { argsParser } from './core/helpers/args'
-import { Digit, Reaction } from './reactions'
-
-type ReactionAddedOrRemoved =
-  | Reaction
-  | `-${tg.TelegramEmoji}`
-  | `-${Digit}${string}`
-
-export type Triggers<C> = MaybeArray<string | RegExp | TriggerFn<C>>
-type TriggerFn<C> = (value: string, ctx: C) => RegExpExecArray | null
-
-export type Predicate<T> = (t: T) => boolean
-export type AsyncPredicate<T> = (t: T) => Promise<boolean>
-
-export type MatchedMiddleware<
-  C extends Context,
-  T extends tt.UpdateType | tt.MessageSubType = 'message' | 'channel_post',
-> = NonemptyReadonlyArray<
-  Middleware<
-    NarrowedContext<C, tt.MountMap[T]> & { match: RegExpExecArray },
-    tt.MountMap[T]
-  >
->
-
-/** Takes: a context type and an update type (or message subtype).
-    Produces: a context that has some properties required, and some undefined.
-    The required ones are those that are always present when the given update (or message) arrives.
-    The undefined ones are those that are always absent when the given update (or message) arrives. */
-/** @deprecated */
-type MatchedContext<
-  C extends Context,
-  T extends tt.UpdateType | tt.MessageSubType,
-> = NarrowedContext<C, tt.MountMap[T]>
-
-function always<T>(x: T) {
-  return () => x
-}
-
-interface StartContextExtn extends tt.CommandContextExtn {
-  /**
-   * @deprecated Use ctx.payload instead
-   */
-  startPayload: string
-}
-
-const anoop = always(Promise.resolve())
-
-export class Composer<C extends Context> implements MiddlewareObj<C> {
-  private handler: MiddlewareFn<C>
-
-  constructor(...fns: ReadonlyArray<Middleware<C>>) {
-    this.handler = Composer.compose(fns)
-  }
-
-  /**
-   * Registers a middleware.
-   */
-  use(...fns: ReadonlyArray<Middleware<C>>) {
-    this.handler = Composer.compose([this.handler, ...fns])
-    return this
-  }
-
-  /**
-   * Registers middleware for handling updates
-   * matching given type guard function.
-   * @deprecated use `Composer::on`
-   */
-  guard<U extends tg.Update>(
-    guardFn: (update: tg.Update) => update is U,
-    ...fns: NonemptyReadonlyArray<Middleware<NarrowedContext<C, U>, U>>
-  ) {
-    return this.use(Composer.guard<C, U>(guardFn, ...fns))
-  }
-
-  /**
-   * Registers middleware for handling updates narrowed by update types or filter queries.
-   */
-  on<Filter extends tt.UpdateType | Guard<C['update']>>(
-    filters: MaybeArray<Filter>,
-    ...fns: NonemptyReadonlyArray<Middleware<FilteredContext<C, Filter>>>
-  ): this
-
-  /**
-   * Registers middleware for handling updates narrowed by update types or message subtypes.
-   * @deprecated Use filter utils instead. Support for Message subtype in `Composer::on` will be removed in Telegraf v5.
-   */
-  on<Filter extends tt.UpdateType | tt.MessageSubType>(
-    filters: MaybeArray<Filter>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<NarrowedContext<C, tt.MountMap[Filter]>, tt.MountMap[Filter]>
-    >
-  ): this
-
-  on<Filter extends tt.UpdateType | tt.MessageSubType | Guard<C['update']>>(
-    filters: MaybeArray<Filter>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        Filter extends tt.MessageSubType
-          ? MatchedContext<C, Filter>
-          : Filter extends tt.UpdateType | Guard<C['update']>
-          ? FilteredContext<C, Filter>
-          : never
-      >
-    >
-  ): this {
-    // @ts-expect-error This should get resolved when the overloads are removed in v5
-    return this.use(Composer.on(filters, ...fns))
-  }
-
-  /**
-   * Registers middleware for handling matching text messages.
-   */
-  hears(
-    triggers: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
-    ...fns: MatchedMiddleware<C, 'text'>
-  ) {
-    return this.use(Composer.hears<C>(triggers, ...fns))
-  }
-
-  /**
-   * Registers middleware for handling specified commands.
-   */
-  command(
-    command: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
-      >
-    >
-  ) {
-    return this.use(Composer.command<C>(command, ...fns))
-  }
-
-  /**
-   * Registers middleware for handling matching callback queries.
-   */
-  action(
-    triggers: Triggers<NarrowedContext<C, tt.MountMap['callback_query']>>,
-    ...fns: MatchedMiddleware<C, 'callback_query'>
-  ) {
-    return this.use(Composer.action<C>(triggers, ...fns))
-  }
-
-  /**
-   * Registers middleware for handling matching inline queries.
-   */
-  inlineQuery(
-    triggers: Triggers<NarrowedContext<C, tt.MountMap['inline_query']>>,
-    ...fns: MatchedMiddleware<C, 'inline_query'>
-  ) {
-    return this.use(Composer.inlineQuery<C>(triggers, ...fns))
-  }
-
-  /**
-   * Registers middleware for handling game queries
-   */
-  gameQuery(
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<
-          C,
-          tg.Update.CallbackQueryUpdate<CallbackQuery.GameQuery>
-        >
-      >
-    >
-  ) {
-    return this.use(Composer.gameQuery(...fns))
-  }
-
-  reaction(
-    reaction: MaybeArray<ReactionAddedOrRemoved>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<C, tg.Update.MessageReactionUpdate> & {
-          match: ReactionAddedOrRemoved
-        },
-        tg.Update.MessageReactionUpdate
-      >
-    >
-  ) {
-    return this.use(Composer.reaction<C>(reaction, ...fns))
-  }
-
-  /**
-   * Registers middleware for dropping matching updates.
-   */
-  drop(predicate: Predicate<C>) {
-    return this.use(Composer.drop(predicate))
-  }
-
-  /** @deprecated use `Composer::drop` */
-  filter(predicate: Predicate<C>) {
-    return this.use(Composer.filter(predicate))
-  }
-
-  private entity<
-    T extends 'message' | 'channel_post' | tt.MessageSubType =
-      | 'message'
-      | 'channel_post',
-  >(
-    predicate:
-      | MaybeArray<string>
-      | ((entity: tg.MessageEntity, s: string, ctx: C) => boolean),
-    ...fns: ReadonlyArray<
-      Middleware<NarrowedContext<C, tt.MountMap[T]>, tt.MountMap[T]>
-    >
-  ) {
-    return this.use(Composer.entity<C, T>(predicate, ...fns))
-  }
-
-  email(email: Triggers<C>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.email<C>(email, ...fns))
-  }
-
-  url(url: Triggers<C>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.url<C>(url, ...fns))
-  }
-
-  textLink(link: Triggers<C>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.textLink<C>(link, ...fns))
-  }
-
-  textMention(mention: Triggers<C>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.textMention<C>(mention, ...fns))
-  }
-
-  mention(mention: MaybeArray<string>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.mention<C>(mention, ...fns))
-  }
-
-  phone(number: Triggers<C>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.phone<C>(number, ...fns))
-  }
-
-  hashtag(hashtag: MaybeArray<string>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.hashtag<C>(hashtag, ...fns))
-  }
-
-  cashtag(cashtag: MaybeArray<string>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.cashtag<C>(cashtag, ...fns))
-  }
-
-  spoiler(text: Triggers<C>, ...fns: MatchedMiddleware<C>) {
-    return this.use(Composer.spoiler<C>(text, ...fns))
-  }
-
-  /**
-   * Registers a middleware for handling /start
-   */
-  start(
-    ...fns: NonemptyReadonlyArray<
-      Middleware<NarrowedContext<C, tt.MountMap['text']> & StartContextExtn>
-    >
-  ) {
-    const handler = Composer.compose(fns)
-    return this.command('start', (ctx, next) =>
-      handler(Object.assign(ctx, { startPayload: ctx.payload }), next)
-    )
-  }
-
-  /**
-   * Registers a middleware for handling /help
-   */
-  help(
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
-      >
-    >
-  ) {
-    return this.command('help', ...fns)
-  }
-
-  /**
-   * Registers a middleware for handling /settings
-   */
-  settings(
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
-      >
-    >
-  ) {
-    return this.command('settings', ...fns)
-  }
-
-  middleware() {
-    return this.handler
-  }
-
-  static reply(...args: Parameters<Context['reply']>): MiddlewareFn<Context> {
-    return (ctx) => ctx.reply(...args)
-  }
-
-  static catch<C extends Context>(
-    errorHandler: (err: unknown, ctx: C) => void,
-    ...fns: ReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    const handler = Composer.compose(fns)
-    // prettier-ignore
-    return (ctx, next) => Promise.resolve(handler(ctx, next))
-      .catch((err) => errorHandler(err, ctx))
-  }
-
-  /**
-   * Generates middleware that runs in the background.
-   */
-  static fork<C extends Context>(middleware: Middleware<C>): MiddlewareFn<C> {
-    const handler = Composer.unwrap(middleware)
-    return async (ctx, next) => {
-      await Promise.all([handler(ctx, anoop), next()])
-    }
-  }
-
-  static tap<C extends Context>(middleware: Middleware<C>): MiddlewareFn<C> {
-    const handler = Composer.unwrap(middleware)
-    return (ctx, next) =>
-      Promise.resolve(handler(ctx, anoop)).then(() => next())
-  }
-
-  /**
-   * Generates middleware that gives up control to the next middleware.
-   */
-  static passThru(): MiddlewareFn<Context> {
-    return (ctx, next) => next()
-  }
-
-  static lazy<C extends Context>(
-    factoryFn: (ctx: C) => MaybePromise<Middleware<C>>
-  ): MiddlewareFn<C> {
-    if (typeof factoryFn !== 'function') {
-      throw new Error('Argument must be a function')
-    }
-    return (ctx, next) =>
-      Promise.resolve(factoryFn(ctx)).then((middleware) =>
-        Composer.unwrap(middleware)(ctx, next)
-      )
-  }
-
-  static log(logFn: (s: string) => void = console.log): MiddlewareFn<Context> {
-    return (ctx, next) => {
-      logFn(JSON.stringify(ctx.update, null, 2))
-      return next()
-    }
-  }
-
-  /**
-   * @param trueMiddleware middleware to run if the predicate returns true
-   * @param falseMiddleware middleware to run if the predicate returns false
-   */
-  static branch<C extends Context>(
-    predicate: boolean | Predicate<C> | AsyncPredicate<C>,
-    trueMiddleware: Middleware<C>,
-    falseMiddleware: Middleware<C>
-  ): MiddlewareFn<C> {
-    if (typeof predicate !== 'function') {
-      return Composer.unwrap(predicate ? trueMiddleware : falseMiddleware)
-    }
-    return Composer.lazy<C>((ctx) =>
-      Promise.resolve(predicate(ctx)).then((value) =>
-        value ? trueMiddleware : falseMiddleware
-      )
-    )
-  }
-
-  /**
-   * Generates optional middleware.
-   * @param predicate predicate to decide on a context object whether to run the middleware
-   * @param fns middleware to run if the predicate returns true
-   */
-  static optional<C extends Context>(
-    predicate: Predicate<C> | AsyncPredicate<C>,
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    return Composer.branch(
-      predicate,
-      Composer.compose(fns),
-      Composer.passThru()
-    )
-  }
-
-  /** @deprecated use `Composer.drop` */
-  static filter<C extends Context>(predicate: Predicate<C>): MiddlewareFn<C> {
-    return Composer.branch(predicate, Composer.passThru(), anoop)
-  }
-
-  /**
-   * Generates middleware for dropping matching updates.
-   */
-  static drop<C extends Context>(predicate: Predicate<C>): MiddlewareFn<C> {
-    return Composer.branch(predicate, anoop, Composer.passThru())
-  }
-
-  static dispatch<
-    C extends Context,
-    Handlers extends Record<string | number | symbol, Middleware<C>>,
-  >(
-    routeFn: (ctx: C) => MaybePromise<keyof Handlers>,
-    handlers: Handlers
-  ): Middleware<C> {
-    return Composer.lazy<C>((ctx) =>
-      Promise.resolve(routeFn(ctx)).then((value) => handlers[value])
-    )
-  }
-
-  // EXPLANATION FOR THE ts-expect-error ANNOTATIONS
-
-  // The annotations around function invocations with `...fns` are there
-  // whenever we perform validation logic that the flow analysis of TypeScript
-  // cannot comprehend. We always make sure that the middleware functions are
-  // only invoked with properly constrained context objects, but this cannot be
-  // determined automatically.
-
-  /**
-   * Generates optional middleware based on a predicate that only operates on `ctx.update`.
-   *
-   * Example:
-   * ```ts
-   * import { Composer, Update } from 'telegraf'
-   *
-   * const predicate = (u): u is Update.MessageUpdate => 'message' in u
-   * const middleware = Composer.guard(predicate, (ctx) => {
-   *   const message = ctx.update.message
-   * })
-   * ```
-   *
-   * Note that `Composer.on('message')` is preferred over this.
-   *
-   * @param guardFn predicate to decide whether to run the middleware based on the `ctx.update` object
-   * @param fns middleware to run if the predicate returns true
-   * @see `Composer.optional` for a more generic version of this method that allows the predicate to operate on `ctx` itself
-   * @deprecated use `Composer.on`
-   */
-  static guard<C extends Context, U extends tg.Update>(
-    guardFn: (u: tg.Update) => u is U,
-    ...fns: NonemptyReadonlyArray<Middleware<NarrowedContext<C, U>, U>>
-  ): MiddlewareFn<C> {
-    return Composer.optional<C>(
-      (ctx) => guardFn(ctx.update),
-      // @ts-expect-error see explanation above
-      ...fns
-    )
-  }
-
-  /**
-   * Generates middleware for handling updates narrowed by update types or filter queries.
-   */
-  static on<
-    Ctx extends Context,
-    Filter extends tt.UpdateType | Guard<Ctx['update']>,
-  >(
-    filters: MaybeArray<Filter>,
-    ...fns: NonemptyReadonlyArray<Middleware<FilteredContext<Ctx, Filter>>>
-  ): MiddlewareFn<Ctx>
-
-  /**
-   * Generates middleware for handling updates narrowed by update types or message subtype.
-   * @deprecated Use filter utils instead. Support for Message subtype in `Composer.on` will be removed in Telegraf v5.
-   */
-  static on<
-    Ctx extends Context,
-    Filter extends tt.UpdateType | tt.MessageSubType,
-  >(
-    filters: MaybeArray<Filter>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<NarrowedContext<Ctx, tt.MountMap[Filter]>, tt.MountMap[Filter]>
-    >
-  ): MiddlewareFn<Ctx>
-
-  static on<
-    Ctx extends Context,
-    Filter extends tt.UpdateType | tt.MessageSubType | Guard<Ctx['update']>,
-  >(
-    updateType: MaybeArray<Filter>,
-    ...fns: NonemptyReadonlyArray<Middleware<Ctx>>
-  ): MiddlewareFn<Ctx> {
-    const filters = Array.isArray(updateType) ? updateType : [updateType]
-
-    const predicate = (update: tg.Update): update is tg.Update => {
-      for (const filter of filters) {
-        if (
-          // TODO: this should change to === 'function' once TS bug is fixed
-          // https://github.com/microsoft/TypeScript/pull/51502
-          typeof filter !== 'string'
-            ? // filter is a type guard
-              filter(update)
-            : // check if filter is the update type
-              filter in update ||
-              // check if filter is the msg type
-              // TODO: remove in v5!
-              ('message' in update && filter in update.message)
-        ) {
-          return true
-        }
-      }
-
-      return false
-    }
-
-    return Composer.optional((ctx) => predicate(ctx.update), ...fns)
-  }
-
-  /**
-   * Generates middleware for handling provided update types.
-   * @deprecated use `Composer.on` instead
-   */
-  static mount = Composer.on
-
-  private static entity<
-    C extends Context,
-    T extends 'message' | 'channel_post' | tt.MessageSubType =
-      | 'message'
-      | 'channel_post',
-  >(
-    predicate:
-      | MaybeArray<string>
-      | ((entity: tg.MessageEntity, s: string, ctx: C) => boolean),
-    ...fns: ReadonlyArray<
-      Middleware<NarrowedContext<C, tt.MountMap[T]>, tt.MountMap[T]>
-    >
-  ): MiddlewareFn<C> {
-    if (typeof predicate !== 'function') {
-      const entityTypes = normaliseTextArguments(predicate)
-      return Composer.entity(({ type }) => entityTypes.includes(type), ...fns)
-    }
-    return Composer.optional<C>(
-      (ctx) => {
-        const msg: tg.Message | undefined = ctx.message ?? ctx.channelPost
-        if (msg === undefined) {
-          return false
-        }
-        const text = getText(msg)
-        const entities = getEntities(msg)
-        if (text === undefined) return false
-        return entities.some((entity) =>
-          predicate(
-            entity,
-            text.substring(entity.offset, entity.offset + entity.length),
-            ctx
-          )
-        )
-      },
-      // @ts-expect-error see explanation above
-      ...fns
-    )
-  }
-
-  static entityText<C extends Context>(
-    entityType: MaybeArray<string>,
-    predicate: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    if (fns.length === 0) {
-      // prettier-ignore
-      return Array.isArray(predicate)
-        // @ts-expect-error predicate is really the middleware
-        ? Composer.entity(entityType, ...predicate)
-        // @ts-expect-error predicate is really the middleware
-        : Composer.entity(entityType, predicate)
-    }
-    const triggers = normaliseTriggers(predicate)
-    return Composer.entity<C>(
-      ({ type }, value, ctx) => {
-        if (type !== entityType) {
-          return false
-        }
-        for (const trigger of triggers) {
-          // @ts-expect-error define so far unknown property `match`
-          if ((ctx.match = trigger(value, ctx))) {
-            return true
-          }
-        }
-        return false
-      },
-      // @ts-expect-error see explanation above
-      ...fns
-    )
-  }
-
-  static email<C extends Context>(
-    email: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>('email', email, ...fns)
-  }
-
-  static phone<C extends Context>(
-    number: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>('phone_number', number, ...fns)
-  }
-
-  static url<C extends Context>(
-    url: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>('url', url, ...fns)
-  }
-
-  static textLink<C extends Context>(
-    link: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>('text_link', link, ...fns)
-  }
-
-  static textMention<C extends Context>(
-    mention: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>('text_mention', mention, ...fns)
-  }
-
-  static mention<C extends Context>(
-    mention: MaybeArray<string>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>(
-      'mention',
-      normaliseTextArguments(mention, '@'),
-      ...fns
-    )
-  }
-
-  static hashtag<C extends Context>(
-    hashtag: MaybeArray<string>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>(
-      'hashtag',
-      normaliseTextArguments(hashtag, '#'),
-      ...fns
-    )
-  }
-
-  static cashtag<C extends Context>(
-    cashtag: MaybeArray<string>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>(
-      'cashtag',
-      normaliseTextArguments(cashtag, '$'),
-      ...fns
-    )
-  }
-
-  static spoiler<C extends Context>(
-    text: Triggers<C>,
-    ...fns: MatchedMiddleware<C>
-  ): MiddlewareFn<C> {
-    return Composer.entityText<C>('spoiler', text, ...fns)
-  }
-
-  private static match<C extends Context>(
-    triggers: ReadonlyArray<TriggerFn<C>>,
-    ...fns: Middleware<C & { match: RegExpExecArray }>[]
-  ): MiddlewareFn<C> {
-    const handler = Composer.compose(fns)
-    return (ctx, next) => {
-      const text =
-        getText(ctx.message) ??
-        getText(ctx.channelPost) ??
-        getText(ctx.callbackQuery) ??
-        ctx.inlineQuery?.query
-      if (text === undefined) return next()
-      for (const trigger of triggers) {
-        const match = trigger(text, ctx)
-        if (match) return handler(Object.assign(ctx, { match }), next)
-      }
-      return next()
-    }
-  }
-
-  /**
-   * Generates middleware for handling matching text messages.
-   */
-  static hears<C extends Context>(
-    triggers: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
-    ...fns: MatchedMiddleware<C, 'text'>
-  ): MiddlewareFn<C> {
-    return Composer.on(
-      'text',
-      Composer.match<NarrowedContext<C, tt.MountMap['text']>>(
-        normaliseTriggers(triggers),
-        ...fns
-      )
-    )
-  }
-
-  /**
-   * Generates middleware for handling specified commands.
-   */
-  static command<C extends Context>(
-    command: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
-      >
-    >
-  ): MiddlewareFn<C> {
-    if (fns.length === 0)
-      // @ts-expect-error command is really the middleware
-      return Composer.entity('bot_command', command)
-
-    const triggers = normaliseTriggers(command)
-    const filter = message('text')
-    const handler = Composer.compose(fns)
-
-    return Composer.on<C, typeof filter>(filter, (ctx, next) => {
-      const { entities } = ctx.message
-      const cmdEntity = entities?.[0]
-      if (cmdEntity?.type !== 'bot_command') return next()
-      if (cmdEntity.offset > 0) return next()
-      const len = cmdEntity.length
-      const text = ctx.message.text
-      const [cmdPart, to] = text.slice(0, len).split('@')
-      if (!cmdPart) return next()
-      // always check for bot's own username case-insensitively
-      if (to && to.toLowerCase() !== ctx.me.toLowerCase()) return next()
-      const command = cmdPart.slice(1)
-      for (const trigger of triggers) {
-        const match = trigger(command, ctx)
-        if (match) {
-          const payloadOffset = len + 1
-          const payload = text.slice(payloadOffset)
-          const c = Object.assign(ctx, { match, command, payload, args: [] })
-          let _args: string[] | undefined = undefined
-          // using defineProperty only to make parsing lazy on access
-          Object.defineProperty(c, 'args', {
-            enumerable: true,
-            configurable: true,
-            get() {
-              if (_args != null) return _args
-              // once parsed, cache and don't parse again on every access
-              return (_args = argsParser(payload, entities, payloadOffset))
-            },
-            set(args: string[]) {
-              _args = args
-            },
-          })
-          return handler(c, next)
-        }
-      }
-      return next()
-    })
-  }
-
-  /**
-   * Generates middleware for handling matching callback queries.
-   */
-  static action<C extends Context>(
-    triggers: Triggers<NarrowedContext<C, tt.MountMap['callback_query']>>,
-    ...fns: MatchedMiddleware<C, 'callback_query'>
-  ): MiddlewareFn<C> {
-    return Composer.on(
-      'callback_query',
-      Composer.match(normaliseTriggers(triggers), ...fns)
-    )
-  }
-
-  /**
-   * Generates middleware for handling matching inline queries.
-   */
-  static inlineQuery<C extends Context>(
-    triggers: Triggers<NarrowedContext<C, tt.MountMap['inline_query']>>,
-    ...fns: MatchedMiddleware<C, 'inline_query'>
-  ): MiddlewareFn<C> {
-    return Composer.on(
-      'inline_query',
-      Composer.match(normaliseTriggers(triggers), ...fns)
-    )
-  }
-
-  static reaction<C extends Context>(
-    reaction: MaybeArray<ReactionAddedOrRemoved>,
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<C, tg.Update.MessageReactionUpdate> & {
-          match: ReactionAddedOrRemoved
-        },
-        tg.Update.MessageReactionUpdate
-      >
-    >
-  ): MiddlewareFn<C> {
-    const reactions = Array.isArray(reaction) ? reaction : [reaction]
-    const handler = Composer.compose(fns)
-
-    return Composer.on<C, 'message_reaction'>(
-      'message_reaction',
-      (ctx, next) => {
-        const match = reactions.find((r) =>
-          typeof r === 'string' && r.startsWith('-')
-            ? ctx.reactions.removed.has(r.slice(1) as Reaction)
-            : ctx.reactions.added.has(r as Reaction)
-        )
-
-        if (match) return handler(Object.assign(ctx, { match }), next)
-        return next()
-      }
-    )
-  }
-
-  /**
-   * Generates middleware responding only to specified users.
-   */
-  static acl<C extends Context>(
-    userId: MaybeArray<number>,
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    if (typeof userId === 'function') {
-      return Composer.optional(userId, ...fns)
-    }
-    const allowed = Array.isArray(userId) ? userId : [userId]
-    // prettier-ignore
-    return Composer.optional((ctx) => !ctx.from || allowed.includes(ctx.from.id), ...fns)
-  }
-
-  private static memberStatus<C extends Context>(
-    status: MaybeArray<tg.ChatMember['status']>,
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    const statuses = Array.isArray(status) ? status : [status]
-    return Composer.optional(
-      async (ctx) => {
-        if (ctx.message === undefined) return false
-        const member = await ctx.getChatMember(ctx.message.from.id)
-        return statuses.includes(member.status)
-      },
-      ...fns
-    )
-  }
-
-  /**
-   * Generates middleware responding only to chat admins and chat creator.
-   */
-  static admin<C extends Context>(
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    return Composer.memberStatus(['administrator', 'creator'], ...fns)
-  }
-
-  /**
-   * Generates middleware responding only to chat creator.
-   */
-  static creator<C extends Context>(
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    return Composer.memberStatus('creator', ...fns)
-  }
-
-  /**
-   * Generates middleware running only in specified chat types.
-   */
-  static chatType<C extends Context>(
-    type: MaybeArray<tg.Chat['type']>,
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    const types = Array.isArray(type) ? type : [type]
-    return Composer.optional(
-      (ctx) => {
-        const chat = ctx.chat
-        return chat !== undefined && types.includes(chat.type)
-      },
-      ...fns
-    )
-  }
-
-  /**
-   * Generates middleware running only in private chats.
-   */
-  static privateChat<C extends Context>(
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    return Composer.chatType('private', ...fns)
-  }
-
-  /**
-   * Generates middleware running only in groups and supergroups.
-   */
-  static groupChat<C extends Context>(
-    ...fns: NonemptyReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    return Composer.chatType(['group', 'supergroup'], ...fns)
-  }
-
-  /**
-   * Generates middleware for handling game queries.
-   */
-  static gameQuery<C extends Context>(
-    ...fns: NonemptyReadonlyArray<
-      Middleware<
-        NarrowedContext<
-          C,
-          tg.Update.CallbackQueryUpdate<CallbackQuery.GameQuery>
-        >
-      >
-    >
-  ): MiddlewareFn<C> {
-    return Composer.guard(callbackQuery('game_short_name'), ...fns)
-  }
-
-  static unwrap<C extends Context>(handler: Middleware<C>): MiddlewareFn<C> {
-    if (!handler) {
-      throw new Error('Handler is undefined')
-    }
-    return 'middleware' in handler ? handler.middleware() : handler
-  }
-
-  static compose<C extends Context>(
-    middlewares: ReadonlyArray<Middleware<C>>
-  ): MiddlewareFn<C> {
-    if (!Array.isArray(middlewares)) {
-      throw new Error('Middlewares must be an array')
-    }
-    if (middlewares.length === 0) {
-      return Composer.passThru()
-    }
-    if (middlewares.length === 1) {
-      // Quite literally asserted in the above condition
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      return Composer.unwrap(middlewares[0]!)
-    }
-    return (ctx, next) => {
-      let index = -1
-      return execute(0, ctx)
-      async function execute(i: number, context: C): Promise<void> {
-        if (!(context instanceof Context)) {
-          throw new Error('next(ctx) called with invalid context')
-        }
-        if (i <= index) {
-          throw new Error('next() called multiple times')
-        }
-        index = i
-        const handler = Composer.unwrap(middlewares[i] ?? next)
-        await handler(context, async (ctx = context) => {
-          await execute(i + 1, ctx)
-        })
-      }
-    }
-  }
-}
-
-function escapeRegExp(s: string) {
-  // $& means the whole matched string
-  return s.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&')
-}
-
-function normaliseTriggers<C extends Context>(
-  triggers: Triggers<C>
-): Array<TriggerFn<C>> {
-  if (!Array.isArray(triggers)) triggers = [triggers]
-
-  return triggers.map((trigger) => {
-    if (!trigger) throw new Error('Invalid trigger')
-    if (typeof trigger === 'function') return trigger
-
-    if (trigger instanceof RegExp)
-      return (value = '') => {
-        trigger.lastIndex = 0
-        return trigger.exec(value)
-      }
-
-    const regex = new RegExp(`^${escapeRegExp(trigger)}$`)
-    return (value: string) => regex.exec(value)
-  })
-}
-
-function getEntities(msg: tg.Message | undefined): tg.MessageEntity[] {
-  if (msg == null) return []
-  if ('caption_entities' in msg) return msg.caption_entities ?? []
-  if ('entities' in msg) return msg.entities ?? []
-  return []
-}
-function getText(
-  msg: tg.Message | tg.CallbackQuery | undefined
-): string | undefined {
-  if (msg == null) return undefined
-  if ('caption' in msg) return msg.caption
-  if ('text' in msg) return msg.text
-  if ('data' in msg) return msg.data
-  if ('game_short_name' in msg) return msg.game_short_name
-  return undefined
-}
-
-function normaliseTextArguments(argument: MaybeArray<string>, prefix = '') {
-  const args = Array.isArray(argument) ? argument : [argument]
-  // prettier-ignore
-  return args
-    .filter(Boolean)
-    .map((arg) => prefix && typeof arg === 'string' && !arg.startsWith(prefix) ? `${prefix}${arg}` : arg)
-}
-
-export default Composer
+/** @format */
+
+import * as tg from './core/types/typegram'
+import * as tt from './telegram-types'
+import { Middleware, MiddlewareFn, MiddlewareObj } from './middleware'
+import Context, { FilteredContext, NarrowedContext } from './context'
+import {
+  MaybeArray,
+  NonemptyReadonlyArray,
+  MaybePromise,
+  Guard,
+} from './core/helpers/util'
+import { type CallbackQuery } from './core/types/typegram'
+import { message, callbackQuery } from './filters'
+import { argsParser } from './core/helpers/args'
+import { Digit, Reaction } from './reactions'
+
+type ReactionAddedOrRemoved =
+  | Reaction
+  | `-${tg.TelegramEmoji}`
+  | `-${Digit}${string}`
+
+export type Triggers<C> = MaybeArray<string | RegExp | TriggerFn<C>>
+type TriggerFn<C> = (value: string, ctx: C) => RegExpExecArray | null
+
+export type Predicate<T> = (t: T) => boolean
+export type AsyncPredicate<T> = (t: T) => Promise<boolean>
+
+export type MatchedMiddleware<
+  C extends Context,
+  T extends tt.UpdateType | tt.MessageSubType = 'message' | 'channel_post',
+> = NonemptyReadonlyArray<
+  Middleware<
+    NarrowedContext<C, tt.MountMap[T]> & { match: RegExpExecArray },
+    tt.MountMap[T]
+  >
+>
+
+/** Takes: a context type and an update type (or message subtype).
+    Produces: a context that has some properties required, and some undefined.
+    The required ones are those that are always present when the given update (or message) arrives.
+    The undefined ones are those that are always absent when the given update (or message) arrives. */
+/** @deprecated */
+type MatchedContext<
+  C extends Context,
+  T extends tt.UpdateType | tt.MessageSubType,
+> = NarrowedContext<C, tt.MountMap[T]>
+
+function always<T>(x: T) {
+  return () => x
+}
+
+interface StartContextExtn extends tt.CommandContextExtn {
+  /**
+   * @deprecated Use ctx.payload instead
+   */
+  startPayload: string
+}
+
+const anoop = always(Promise.resolve())
+
+export class Composer<C extends Context> implements MiddlewareObj<C> {
+  private handler: MiddlewareFn<C>
+
+  constructor(...fns: ReadonlyArray<Middleware<C>>) {
+    this.handler = Composer.compose(fns)
+  }
+
+  /**
+   * Registers a middleware.
+   */
+  use(...fns: ReadonlyArray<Middleware<C>>) {
+    this.handler = Composer.compose([this.handler, ...fns])
+    return this
+  }
+
+  /**
+   * Registers middleware for handling updates
+   * matching given type guard function.
+   * @deprecated use `Composer::on`
+   */
+  guard<U extends tg.Update>(
+    guardFn: (update: tg.Update) => update is U,
+    ...fns: NonemptyReadonlyArray<Middleware<NarrowedContext<C, U>, U>>
+  ) {
+    return this.use(Composer.guard<C, U>(guardFn, ...fns))
+  }
+
+  /**
+   * Registers middleware for handling updates narrowed by update types or filter queries.
+   */
+  on<Filter extends tt.UpdateType | Guard<C['update']>>(
+    filters: MaybeArray<Filter>,
+    ...fns: NonemptyReadonlyArray<Middleware<FilteredContext<C, Filter>>>
+  ): this
+
+  /**
+   * Registers middleware for handling updates narrowed by update types or message subtypes.
+   * @deprecated Use filter utils instead. Support for Message subtype in `Composer::on` will be removed in Telegraf v5.
+   */
+  on<Filter extends tt.UpdateType | tt.MessageSubType>(
+    filters: MaybeArray<Filter>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<NarrowedContext<C, tt.MountMap[Filter]>, tt.MountMap[Filter]>
+    >
+  ): this
+
+  on<Filter extends tt.UpdateType | tt.MessageSubType | Guard<C['update']>>(
+    filters: MaybeArray<Filter>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        Filter extends tt.MessageSubType
+          ? MatchedContext<C, Filter>
+          : Filter extends tt.UpdateType | Guard<C['update']>
+          ? FilteredContext<C, Filter>
+          : never
+      >
+    >
+  ): this {
+    // @ts-expect-error This should get resolved when the overloads are removed in v5
+    return this.use(Composer.on(filters, ...fns))
+  }
+
+  /**
+   * Registers middleware for handling matching text messages.
+   */
+  hears(
+    triggers: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
+    ...fns: MatchedMiddleware<C, 'text'>
+  ) {
+    return this.use(Composer.hears<C>(triggers, ...fns))
+  }
+
+  /**
+   * Registers middleware for handling specified commands.
+   */
+  command(
+    command: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
+      >
+    >
+  ) {
+    return this.use(Composer.command<C>(command, ...fns))
+  }
+
+  /**
+   * Registers middleware for handling matching callback queries.
+   */
+  action(
+    triggers: Triggers<NarrowedContext<C, tt.MountMap['callback_query']>>,
+    ...fns: MatchedMiddleware<C, 'callback_query'>
+  ) {
+    return this.use(Composer.action<C>(triggers, ...fns))
+  }
+
+  /**
+   * Registers middleware for handling matching inline queries.
+   */
+  inlineQuery(
+    triggers: Triggers<NarrowedContext<C, tt.MountMap['inline_query']>>,
+    ...fns: MatchedMiddleware<C, 'inline_query'>
+  ) {
+    return this.use(Composer.inlineQuery<C>(triggers, ...fns))
+  }
+
+  /**
+   * Registers middleware for handling game queries
+   */
+  gameQuery(
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<
+          C,
+          tg.Update.CallbackQueryUpdate<CallbackQuery.GameQuery>
+        >
+      >
+    >
+  ) {
+    return this.use(Composer.gameQuery(...fns))
+  }
+
+  reaction(
+    reaction: MaybeArray<ReactionAddedOrRemoved>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<C, tg.Update.MessageReactionUpdate> & {
+          match: ReactionAddedOrRemoved
+        },
+        tg.Update.MessageReactionUpdate
+      >
+    >
+  ) {
+    return this.use(Composer.reaction<C>(reaction, ...fns))
+  }
+
+  /**
+   * Registers middleware for dropping matching updates.
+   */
+  drop(predicate: Predicate<C>) {
+    return this.use(Composer.drop(predicate))
+  }
+
+  /** @deprecated use `Composer::drop` */
+  filter(predicate: Predicate<C>) {
+    return this.use(Composer.filter(predicate))
+  }
+
+  private entity<
+    T extends 'message' | 'channel_post' | tt.MessageSubType =
+      | 'message'
+      | 'channel_post',
+  >(
+    predicate:
+      | MaybeArray<string>
+      | ((entity: tg.MessageEntity, s: string, ctx: C) => boolean),
+    ...fns: ReadonlyArray<
+      Middleware<NarrowedContext<C, tt.MountMap[T]>, tt.MountMap[T]>
+    >
+  ) {
+    return this.use(Composer.entity<C, T>(predicate, ...fns))
+  }
+
+  email(email: Triggers<C>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.email<C>(email, ...fns))
+  }
+
+  url(url: Triggers<C>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.url<C>(url, ...fns))
+  }
+
+  textLink(link: Triggers<C>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.textLink<C>(link, ...fns))
+  }
+
+  textMention(mention: Triggers<C>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.textMention<C>(mention, ...fns))
+  }
+
+  mention(mention: MaybeArray<string>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.mention<C>(mention, ...fns))
+  }
+
+  phone(number: Triggers<C>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.phone<C>(number, ...fns))
+  }
+
+  hashtag(hashtag: MaybeArray<string>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.hashtag<C>(hashtag, ...fns))
+  }
+
+  cashtag(cashtag: MaybeArray<string>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.cashtag<C>(cashtag, ...fns))
+  }
+
+  spoiler(text: Triggers<C>, ...fns: MatchedMiddleware<C>) {
+    return this.use(Composer.spoiler<C>(text, ...fns))
+  }
+
+  /**
+   * Registers a middleware for handling /start
+   */
+  start(
+    ...fns: NonemptyReadonlyArray<
+      Middleware<NarrowedContext<C, tt.MountMap['text']> & StartContextExtn>
+    >
+  ) {
+    const handler = Composer.compose(fns)
+    return this.command('start', (ctx, next) =>
+      handler(Object.assign(ctx, { startPayload: ctx.payload }), next)
+    )
+  }
+
+  /**
+   * Registers a middleware for handling /help
+   */
+  help(
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
+      >
+    >
+  ) {
+    return this.command('help', ...fns)
+  }
+
+  /**
+   * Registers a middleware for handling /settings
+   */
+  settings(
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
+      >
+    >
+  ) {
+    return this.command('settings', ...fns)
+  }
+
+  middleware() {
+    return this.handler
+  }
+
+  static reply(...args: Parameters<Context['reply']>): MiddlewareFn<Context> {
+    return (ctx) => ctx.reply(...args)
+  }
+
+  static catch<C extends Context>(
+    errorHandler: (err: unknown, ctx: C) => void,
+    ...fns: ReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    const handler = Composer.compose(fns)
+    // prettier-ignore
+    return (ctx, next) => Promise.resolve(handler(ctx, next))
+      .catch((err) => errorHandler(err, ctx))
+  }
+
+  /**
+   * Generates middleware that runs in the background.
+   */
+  static fork<C extends Context>(middleware: Middleware<C>): MiddlewareFn<C> {
+    const handler = Composer.unwrap(middleware)
+    return async (ctx, next) => {
+      await Promise.all([handler(ctx, anoop), next()])
+    }
+  }
+
+  static tap<C extends Context>(middleware: Middleware<C>): MiddlewareFn<C> {
+    const handler = Composer.unwrap(middleware)
+    return (ctx, next) =>
+      Promise.resolve(handler(ctx, anoop)).then(() => next())
+  }
+
+  /**
+   * Generates middleware that gives up control to the next middleware.
+   */
+  static passThru(): MiddlewareFn<Context> {
+    return (ctx, next) => next()
+  }
+
+  static lazy<C extends Context>(
+    factoryFn: (ctx: C) => MaybePromise<Middleware<C>>
+  ): MiddlewareFn<C> {
+    if (typeof factoryFn !== 'function') {
+      throw new Error('Argument must be a function')
+    }
+    return (ctx, next) =>
+      Promise.resolve(factoryFn(ctx)).then((middleware) =>
+        Composer.unwrap(middleware)(ctx, next)
+      )
+  }
+
+  static log(logFn: (s: string) => void = console.log): MiddlewareFn<Context> {
+    return (ctx, next) => {
+      logFn(JSON.stringify(ctx.update, null, 2))
+      return next()
+    }
+  }
+
+  /**
+   * @param trueMiddleware middleware to run if the predicate returns true
+   * @param falseMiddleware middleware to run if the predicate returns false
+   */
+  static branch<C extends Context>(
+    predicate: boolean | Predicate<C> | AsyncPredicate<C>,
+    trueMiddleware: Middleware<C>,
+    falseMiddleware: Middleware<C>
+  ): MiddlewareFn<C> {
+    if (typeof predicate !== 'function') {
+      return Composer.unwrap(predicate ? trueMiddleware : falseMiddleware)
+    }
+    return Composer.lazy<C>((ctx) =>
+      Promise.resolve(predicate(ctx)).then((value) =>
+        value ? trueMiddleware : falseMiddleware
+      )
+    )
+  }
+
+  /**
+   * Generates optional middleware.
+   * @param predicate predicate to decide on a context object whether to run the middleware
+   * @param fns middleware to run if the predicate returns true
+   */
+  static optional<C extends Context>(
+    predicate: Predicate<C> | AsyncPredicate<C>,
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    return Composer.branch(
+      predicate,
+      Composer.compose(fns),
+      Composer.passThru()
+    )
+  }
+
+  /** @deprecated use `Composer.drop` */
+  static filter<C extends Context>(predicate: Predicate<C>): MiddlewareFn<C> {
+    return Composer.branch(predicate, Composer.passThru(), anoop)
+  }
+
+  /**
+   * Generates middleware for dropping matching updates.
+   */
+  static drop<C extends Context>(predicate: Predicate<C>): MiddlewareFn<C> {
+    return Composer.branch(predicate, anoop, Composer.passThru())
+  }
+
+  static dispatch<
+    C extends Context,
+    Handlers extends Record<string | number | symbol, Middleware<C>>,
+  >(
+    routeFn: (ctx: C) => MaybePromise<keyof Handlers>,
+    handlers: Handlers
+  ): Middleware<C> {
+    return Composer.lazy<C>((ctx) =>
+      Promise.resolve(routeFn(ctx)).then((value) => handlers[value])
+    )
+  }
+
+  // EXPLANATION FOR THE ts-expect-error ANNOTATIONS
+
+  // The annotations around function invocations with `...fns` are there
+  // whenever we perform validation logic that the flow analysis of TypeScript
+  // cannot comprehend. We always make sure that the middleware functions are
+  // only invoked with properly constrained context objects, but this cannot be
+  // determined automatically.
+
+  /**
+   * Generates optional middleware based on a predicate that only operates on `ctx.update`.
+   *
+   * Example:
+   * ```ts
+   * import { Composer, Update } from 'telegraf'
+   *
+   * const predicate = (u): u is Update.MessageUpdate => 'message' in u
+   * const middleware = Composer.guard(predicate, (ctx) => {
+   *   const message = ctx.update.message
+   * })
+   * ```
+   *
+   * Note that `Composer.on('message')` is preferred over this.
+   *
+   * @param guardFn predicate to decide whether to run the middleware based on the `ctx.update` object
+   * @param fns middleware to run if the predicate returns true
+   * @see `Composer.optional` for a more generic version of this method that allows the predicate to operate on `ctx` itself
+   * @deprecated use `Composer.on`
+   */
+  static guard<C extends Context, U extends tg.Update>(
+    guardFn: (u: tg.Update) => u is U,
+    ...fns: NonemptyReadonlyArray<Middleware<NarrowedContext<C, U>, U>>
+  ): MiddlewareFn<C> {
+    return Composer.optional<C>(
+      (ctx) => guardFn(ctx.update),
+      // @ts-expect-error see explanation above
+      ...fns
+    )
+  }
+
+  /**
+   * Generates middleware for handling updates narrowed by update types or filter queries.
+   */
+  static on<
+    Ctx extends Context,
+    Filter extends tt.UpdateType | Guard<Ctx['update']>,
+  >(
+    filters: MaybeArray<Filter>,
+    ...fns: NonemptyReadonlyArray<Middleware<FilteredContext<Ctx, Filter>>>
+  ): MiddlewareFn<Ctx>
+
+  /**
+   * Generates middleware for handling updates narrowed by update types or message subtype.
+   * @deprecated Use filter utils instead. Support for Message subtype in `Composer.on` will be removed in Telegraf v5.
+   */
+  static on<
+    Ctx extends Context,
+    Filter extends tt.UpdateType | tt.MessageSubType,
+  >(
+    filters: MaybeArray<Filter>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<NarrowedContext<Ctx, tt.MountMap[Filter]>, tt.MountMap[Filter]>
+    >
+  ): MiddlewareFn<Ctx>
+
+  static on<
+    Ctx extends Context,
+    Filter extends tt.UpdateType | tt.MessageSubType | Guard<Ctx['update']>,
+  >(
+    updateType: MaybeArray<Filter>,
+    ...fns: NonemptyReadonlyArray<Middleware<Ctx>>
+  ): MiddlewareFn<Ctx> {
+    const filters = Array.isArray(updateType) ? updateType : [updateType]
+
+    const predicate = (update: tg.Update): update is tg.Update => {
+      for (const filter of filters) {
+        if (
+          // TODO: this should change to === 'function' once TS bug is fixed
+          // https://github.com/microsoft/TypeScript/pull/51502
+          typeof filter !== 'string'
+            ? // filter is a type guard
+              filter(update)
+            : // check if filter is the update type
+              filter in update ||
+              // check if filter is the msg type
+              // TODO: remove in v5!
+              ('message' in update && filter in update.message)
+        ) {
+          return true
+        }
+      }
+
+      return false
+    }
+
+    return Composer.optional((ctx) => predicate(ctx.update), ...fns)
+  }
+
+  /**
+   * Generates middleware for handling provided update types.
+   * @deprecated use `Composer.on` instead
+   */
+  static mount = Composer.on
+
+  private static entity<
+    C extends Context,
+    T extends 'message' | 'channel_post' | tt.MessageSubType =
+      | 'message'
+      | 'channel_post',
+  >(
+    predicate:
+      | MaybeArray<string>
+      | ((entity: tg.MessageEntity, s: string, ctx: C) => boolean),
+    ...fns: ReadonlyArray<
+      Middleware<NarrowedContext<C, tt.MountMap[T]>, tt.MountMap[T]>
+    >
+  ): MiddlewareFn<C> {
+    if (typeof predicate !== 'function') {
+      const entityTypes = normaliseTextArguments(predicate)
+      return Composer.entity(({ type }) => entityTypes.includes(type), ...fns)
+    }
+    return Composer.optional<C>(
+      (ctx) => {
+        const msg: tg.Message | undefined = ctx.message ?? ctx.channelPost
+        if (msg === undefined) {
+          return false
+        }
+        const text = getText(msg)
+        const entities = getEntities(msg)
+        if (text === undefined) return false
+        return entities.some((entity) =>
+          predicate(
+            entity,
+            text.substring(entity.offset, entity.offset + entity.length),
+            ctx
+          )
+        )
+      },
+      // @ts-expect-error see explanation above
+      ...fns
+    )
+  }
+
+  static entityText<C extends Context>(
+    entityType: MaybeArray<string>,
+    predicate: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    if (fns.length === 0) {
+      // prettier-ignore
+      return Array.isArray(predicate)
+        // @ts-expect-error predicate is really the middleware
+        ? Composer.entity(entityType, ...predicate)
+        // @ts-expect-error predicate is really the middleware
+        : Composer.entity(entityType, predicate)
+    }
+    const triggers = normaliseTriggers(predicate)
+    return Composer.entity<C>(
+      ({ type }, value, ctx) => {
+        if (type !== entityType) {
+          return false
+        }
+        for (const trigger of triggers) {
+          // @ts-expect-error define so far unknown property `match`
+          if ((ctx.match = trigger(value, ctx))) {
+            return true
+          }
+        }
+        return false
+      },
+      // @ts-expect-error see explanation above
+      ...fns
+    )
+  }
+
+  static email<C extends Context>(
+    email: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>('email', email, ...fns)
+  }
+
+  static phone<C extends Context>(
+    number: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>('phone_number', number, ...fns)
+  }
+
+  static url<C extends Context>(
+    url: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>('url', url, ...fns)
+  }
+
+  static textLink<C extends Context>(
+    link: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>('text_link', link, ...fns)
+  }
+
+  static textMention<C extends Context>(
+    mention: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>('text_mention', mention, ...fns)
+  }
+
+  static mention<C extends Context>(
+    mention: MaybeArray<string>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>(
+      'mention',
+      normaliseTextArguments(mention, '@'),
+      ...fns
+    )
+  }
+
+  static hashtag<C extends Context>(
+    hashtag: MaybeArray<string>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>(
+      'hashtag',
+      normaliseTextArguments(hashtag, '#'),
+      ...fns
+    )
+  }
+
+  static cashtag<C extends Context>(
+    cashtag: MaybeArray<string>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>(
+      'cashtag',
+      normaliseTextArguments(cashtag, '$'),
+      ...fns
+    )
+  }
+
+  static spoiler<C extends Context>(
+    text: Triggers<C>,
+    ...fns: MatchedMiddleware<C>
+  ): MiddlewareFn<C> {
+    return Composer.entityText<C>('spoiler', text, ...fns)
+  }
+
+  private static match<C extends Context>(
+    triggers: ReadonlyArray<TriggerFn<C>>,
+    ...fns: Middleware<C & { match: RegExpExecArray }>[]
+  ): MiddlewareFn<C> {
+    const handler = Composer.compose(fns)
+    return (ctx, next) => {
+      const text =
+        getText(ctx.message) ??
+        getText(ctx.channelPost) ??
+        getText(ctx.callbackQuery) ??
+        ctx.inlineQuery?.query
+      if (text === undefined) return next()
+      for (const trigger of triggers) {
+        const match = trigger(text, ctx)
+        if (match) return handler(Object.assign(ctx, { match }), next)
+      }
+      return next()
+    }
+  }
+
+  /**
+   * Generates middleware for handling matching text messages.
+   */
+  static hears<C extends Context>(
+    triggers: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
+    ...fns: MatchedMiddleware<C, 'text'>
+  ): MiddlewareFn<C> {
+    return Composer.on(
+      'text',
+      Composer.match<NarrowedContext<C, tt.MountMap['text']>>(
+        normaliseTriggers(triggers),
+        ...fns
+      )
+    )
+  }
+
+  /**
+   * Generates middleware for handling specified commands.
+   */
+  static command<C extends Context>(
+    command: Triggers<NarrowedContext<C, tt.MountMap['text']>>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<C, tt.MountMap['text']> & tt.CommandContextExtn
+      >
+    >
+  ): MiddlewareFn<C> {
+    if (fns.length === 0)
+      // @ts-expect-error command is really the middleware
+      return Composer.entity('bot_command', command)
+
+    const triggers = normaliseTriggers(command)
+    const filter = message('text')
+    const handler = Composer.compose(fns)
+
+    return Composer.on<C, typeof filter>(filter, (ctx, next) => {
+      const { entities } = ctx.message
+      const cmdEntity = entities?.[0]
+      if (cmdEntity?.type !== 'bot_command') return next()
+      if (cmdEntity.offset > 0) return next()
+      const len = cmdEntity.length
+      const text = ctx.message.text
+      const [cmdPart, to] = text.slice(0, len).split('@')
+      if (!cmdPart) return next()
+      // always check for bot's own username case-insensitively
+      if (to && to.toLowerCase() !== ctx.me.toLowerCase()) return next()
+      const command = cmdPart.slice(1)
+      for (const trigger of triggers) {
+        const match = trigger(command, ctx)
+        if (match) {
+          const payloadOffset = len + 1
+          const payload = text.slice(payloadOffset)
+          const c = Object.assign(ctx, { match, command, payload, args: [] })
+          let _args: string[] | undefined = undefined
+          // using defineProperty only to make parsing lazy on access
+          Object.defineProperty(c, 'args', {
+            enumerable: true,
+            configurable: true,
+            get() {
+              if (_args != null) return _args
+              // once parsed, cache and don't parse again on every access
+              return (_args = argsParser(payload, entities, payloadOffset))
+            },
+            set(args: string[]) {
+              _args = args
+            },
+          })
+          return handler(c, next)
+        }
+      }
+      return next()
+    })
+  }
+
+  /**
+   * Generates middleware for handling matching callback queries.
+   */
+  static action<C extends Context>(
+    triggers: Triggers<NarrowedContext<C, tt.MountMap['callback_query']>>,
+    ...fns: MatchedMiddleware<C, 'callback_query'>
+  ): MiddlewareFn<C> {
+    return Composer.on(
+      'callback_query',
+      Composer.match(normaliseTriggers(triggers), ...fns)
+    )
+  }
+
+  /**
+   * Generates middleware for handling matching inline queries.
+   */
+  static inlineQuery<C extends Context>(
+    triggers: Triggers<NarrowedContext<C, tt.MountMap['inline_query']>>,
+    ...fns: MatchedMiddleware<C, 'inline_query'>
+  ): MiddlewareFn<C> {
+    return Composer.on(
+      'inline_query',
+      Composer.match(normaliseTriggers(triggers), ...fns)
+    )
+  }
+
+  static reaction<C extends Context>(
+    reaction: MaybeArray<ReactionAddedOrRemoved>,
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<C, tg.Update.MessageReactionUpdate> & {
+          match: ReactionAddedOrRemoved
+        },
+        tg.Update.MessageReactionUpdate
+      >
+    >
+  ): MiddlewareFn<C> {
+    const reactions = Array.isArray(reaction) ? reaction : [reaction]
+    const handler = Composer.compose(fns)
+
+    return Composer.on<C, 'message_reaction'>(
+      'message_reaction',
+      (ctx, next) => {
+        const match = reactions.find((r) =>
+          typeof r === 'string' && r.startsWith('-')
+            ? ctx.reactions.removed.has(r.slice(1) as Reaction)
+            : ctx.reactions.added.has(r as Reaction)
+        )
+
+        if (match) return handler(Object.assign(ctx, { match }), next)
+        return next()
+      }
+    )
+  }
+
+  /**
+   * Generates middleware responding only to specified users.
+   */
+  static acl<C extends Context>(
+    userId: MaybeArray<number>,
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    if (typeof userId === 'function') {
+      return Composer.optional(userId, ...fns)
+    }
+    const allowed = Array.isArray(userId) ? userId : [userId]
+    // prettier-ignore
+    return Composer.optional((ctx) => !ctx.from || allowed.includes(ctx.from.id), ...fns)
+  }
+
+  private static memberStatus<C extends Context>(
+    status: MaybeArray<tg.ChatMember['status']>,
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    const statuses = Array.isArray(status) ? status : [status]
+    return Composer.optional(
+      async (ctx) => {
+        if (ctx.message === undefined) return false
+        const member = await ctx.getChatMember(ctx.message.from.id)
+        return statuses.includes(member.status)
+      },
+      ...fns
+    )
+  }
+
+  /**
+   * Generates middleware responding only to chat admins and chat creator.
+   */
+  static admin<C extends Context>(
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    return Composer.memberStatus(['administrator', 'creator'], ...fns)
+  }
+
+  /**
+   * Generates middleware responding only to chat creator.
+   */
+  static creator<C extends Context>(
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    return Composer.memberStatus('creator', ...fns)
+  }
+
+  /**
+   * Generates middleware running only in specified chat types.
+   */
+  static chatType<C extends Context>(
+    type: MaybeArray<tg.Chat['type']>,
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    const types = Array.isArray(type) ? type : [type]
+    return Composer.optional(
+      (ctx) => {
+        const chat = ctx.chat
+        return chat !== undefined && types.includes(chat.type)
+      },
+      ...fns
+    )
+  }
+
+  /**
+   * Generates middleware running only in private chats.
+   */
+  static privateChat<C extends Context>(
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    return Composer.chatType('private', ...fns)
+  }
+
+  /**
+   * Generates middleware running only in groups and supergroups.
+   */
+  static groupChat<C extends Context>(
+    ...fns: NonemptyReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    return Composer.chatType(['group', 'supergroup'], ...fns)
+  }
+
+  /**
+   * Generates middleware for handling game queries.
+   */
+  static gameQuery<C extends Context>(
+    ...fns: NonemptyReadonlyArray<
+      Middleware<
+        NarrowedContext<
+          C,
+          tg.Update.CallbackQueryUpdate<CallbackQuery.GameQuery>
+        >
+      >
+    >
+  ): MiddlewareFn<C> {
+    return Composer.guard(callbackQuery('game_short_name'), ...fns)
+  }
+
+  static unwrap<C extends Context>(handler: Middleware<C>): MiddlewareFn<C> {
+    if (!handler) {
+      throw new Error('Handler is undefined')
+    }
+    return 'middleware' in handler ? handler.middleware() : handler
+  }
+
+  static compose<C extends Context>(
+    middlewares: ReadonlyArray<Middleware<C>>
+  ): MiddlewareFn<C> {
+    if (!Array.isArray(middlewares)) {
+      throw new Error('Middlewares must be an array')
+    }
+    if (middlewares.length === 0) {
+      return Composer.passThru()
+    }
+    if (middlewares.length === 1) {
+      // Quite literally asserted in the above condition
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      return Composer.unwrap(middlewares[0]!)
+    }
+    return (ctx, next) => {
+      let index = -1
+      return execute(0, ctx)
+      async function execute(i: number, context: C): Promise<void> {
+        if (!(context instanceof Context)) {
+          throw new Error('next(ctx) called with invalid context')
+        }
+        if (i <= index) {
+          throw new Error('next() called multiple times')
+        }
+        index = i
+        const handler = Composer.unwrap(middlewares[i] ?? next)
+        await handler(context, async (ctx = context) => {
+          await execute(i + 1, ctx)
+        })
+      }
+    }
+  }
+}
+
+function escapeRegExp(s: string) {
+  // $& means the whole matched string
+  return s.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&')
+}
+
+function normaliseTriggers<C extends Context>(
+  triggers: Triggers<C>
+): Array<TriggerFn<C>> {
+  if (!Array.isArray(triggers)) triggers = [triggers]
+
+  return triggers.map((trigger) => {
+    if (!trigger) throw new Error('Invalid trigger')
+    if (typeof trigger === 'function') return trigger
+
+    if (trigger instanceof RegExp)
+      return (value = '') => {
+        trigger.lastIndex = 0
+        return trigger.exec(value)
+      }
+
+    const regex = new RegExp(`^${escapeRegExp(trigger)}$`)
+    return (value: string) => regex.exec(value)
+  })
+}
+
+function getEntities(msg: tg.Message | undefined): tg.MessageEntity[] {
+  if (msg == null) return []
+  if ('caption_entities' in msg) return msg.caption_entities ?? []
+  if ('entities' in msg) return msg.entities ?? []
+  return []
+}
+function getText(
+  msg: tg.Message | tg.CallbackQuery | undefined
+): string | undefined {
+  if (msg == null) return undefined
+  if ('caption' in msg) return msg.caption
+  if ('text' in msg) return msg.text
+  if ('data' in msg) return msg.data
+  if ('game_short_name' in msg) return msg.game_short_name
+  return undefined
+}
+
+function normaliseTextArguments(argument: MaybeArray<string>, prefix = '') {
+  const args = Array.isArray(argument) ? argument : [argument]
+  // prettier-ignore
+  return args
+    .filter(Boolean)
+    .map((arg) => prefix && typeof arg === 'string' && !arg.startsWith(prefix) ? `${prefix}${arg}` : arg)
+}
+
+export default Composer