EventOrMessageListenerDefinition

Kind: Interface

Source: packages/microservices/listener-metadata-explorer.ts

Part of: Microservices

EventOrMessageListenerDefinition describes a discovered microservice listener method and the metadata required to register it with a transport strategy. It unifies request-response message handlers and event handlers by storing their patterns, callback target, transport, and additional transport-specific options.

Properties

Diagram

mermaid
graph LR
  Explorer[ListenerMetadataExplorer] --> Definition[EventOrMessageListenerDefinition]

  Definition --> Patterns[patterns: PatternMetadata[]]
  Definition --> Method[methodKey: string]
  Definition --> Event[isEventHandler: boolean]
  Definition --> Callback[targetCallback]
  Definition --> Transport[transport: Transport]
  Definition --> Extras[extras: Record<string, any>]

  Patterns --> Server[Microservice Server]
  Callback --> Server
  Transport --> Server
  Extras --> Server

Usage

ts
import { Transport } from '@nestjs/microservices';
import type { EventOrMessageListenerDefinition } from './listener-metadata-explorer';

const listener: EventOrMessageListenerDefinition = {
  patterns: [
    {
      cmd: 'get_user',
    },
  ],
  methodKey: 'getUser',
  isEventHandler: false,
  targetCallback: async (data: { id: string }) => {
    return { id: data.id, name: 'Ada Lovelace' };
  },
  transport: Transport.TCP,
  extras: {
    queue: 'users',
  },
};

// A listener explorer or server adapter can use this metadata to bind
// `targetCallback` to each configured pattern for the selected transport.

AI Coding Instructions

• Preserve the distinction between message handlers and event handlers: isEventHandler: false expects a response, while true represents a fire-and-forget event listener.
• Treat patterns as the authoritative routing metadata; a single listener may support multiple patterns.
• Keep targetCallback bound to the correct controller/provider instance before invoking it, especially when extracted from a class prototype.
• Use transport and extras together when registering handlers, since extras may contain adapter-specific configuration such as queue or subscription options.
• Avoid narrowing extras globally; validate or cast its values within the transport-specific integration layer.

How it works

EventOrMessageListenerDefinition

EventOrMessageListenerDefinition is an exported TypeScript interface describing metadata extracted for one controller method marked as a microservice event or message handler. It contains the handler’s patterns, method name, handler callback, event/message classification, and optional transport-specific metadata. packages/microservices/listener-metadata-explorer.ts:21-28