# EventOrMessageListenerDefinition

**Kind:** Interface

**Source:** [`packages/microservices/listener-metadata-explorer.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/listener-metadata-explorer.ts#L21)

**Part of:** [Microservices](subsystem-packages-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

| Property | Type |
|---|---|
| `patterns` | `PatternMetadata[]` |
| `methodKey` | `string` |
| `isEventHandler` | `boolean` |
| `targetCallback` | `(...args: any[]) => any` |
| `transport` | `Transport` |
| `extras` | `Record<string, any>` |

## 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`](packages/microservices/listener-metadata-explorer.ts#L21-L28)