# GatewayMetadataExplorer

**Kind:** Class

**Source:** [`packages/websockets/gateway-metadata-explorer.ts`](https://github.com/nestjs/nest/blob/master/packages/websockets/gateway-metadata-explorer.ts#L22)

**Part of:** [Websockets](subsystem-packages-websockets)

`GatewayMetadataExplorer` discovers WebSocket gateway methods decorated as message handlers or lifecycle hooks. It uses Nest’s metadata scanning utilities to convert gateway method metadata into `MessageMappingProperties` entries that the WebSocket runtime can register and invoke.

## Methods

| Method | Signature | Returns |
|---|---|---|
| `explore` | `explore(instance: NestGateway)` | `MessageMappingProperties[]` |
| `exploreMethodMetadata` | `exploreMethodMetadata(instancePrototype: object, methodName: string)` | `MessageMappingProperties | null` |
| `scanForServerHooks` | `scanForServerHooks(instance: NestGateway)` | `IterableIterator<string>` |

## Where it refuses work

- `GatewayMetadataExplorer` stops the work with an early return when `isUndefined(isMessageMapping)`.
- `GatewayMetadataExplorer` stops the work with an early return when `!paramsMetadata`.

## Diagram

```mermaid
graph LR
  Gateway[Gateway instance] --> Explorer[GatewayMetadataExplorer]
  Explorer --> Scanner[MetadataScanner]
  Scanner --> Methods[Gateway prototype methods]
  Methods --> Accessor[MetadataAccessor]
  Accessor --> Mappings[MessageMappingProperties]
  Accessor --> Hooks[Gateway lifecycle hook names]
```

## Usage

```ts
import { GatewayMetadataExplorer } from '@nestjs/websockets';

const explorer = app.get(GatewayMetadataExplorer);
const gatewayInstance = app.get(EventsGateway);

// Discover methods decorated with @SubscribeMessage()
const messageMappings = explorer.explore(gatewayInstance);

for (const mapping of messageMappings) {
  console.log(`Message "${mapping.message}" handled by ${mapping.methodName}`);
}

// Discover lifecycle methods such as handleConnection or handleDisconnect
for (const hookName of explorer.scanForServerHooks(gatewayInstance)) {
  console.log(`Gateway hook found: ${hookName}`);
}
```

## AI Coding Instructions

- Use `explore()` to discover `@SubscribeMessage()` handlers; do not manually inspect gateway methods when metadata-based discovery is available.
- Keep message handler decorators on prototype methods, since metadata scanning operates on the gateway prototype.
- Treat `exploreMethodMetadata()` returning `null` as an expected result for methods without message-mapping metadata.
- Use `scanForServerHooks()` when integrating gateway lifecycle methods such as connection, disconnect, and initialization hooks.
- Prefer resolving this class through Nest dependency injection rather than constructing it manually, because it depends on `MetadataScanner` and `MetadataAccessor`.