npm package: @hyper-graph/ws-adapter
Description: Websocket adapter for nestjs framework
Latest version: 0.7.0

NestJS Websocket Adapter

# Motivation:
Websocket adapters, which provided by NestJS, are very simple and cannot be used in large applications.
They can only receive messages, send replies, without correlation id, and send events.
Using them you can't reply with correlation id in common, can't verify connect and etc.
This adapter try to resolve more of common cases.

# Features

## Correlation ID
Then you return data from a gateway it will return with correlationId which was received from client.
This behavior can be configured by adapter options.

## Events
It's not a feature, but events has different api than nestjs adapters.
You can emit an event on connect and all data that you pass will be sent to client with wrapping into protocol.

## Formatter
You can specify a formatter for your application. It means you can use JSON, yml, xml, binary or another format of data.

## Protocol
Protocol control all data that receive or send application and wrap it into control object.
Protocol can receive correlationId and send it in response with data what return message handler.
You can also pass your own implementation of protocol.

## Connect verification
You can set connect verification handler. This handler will be called for each connect request.
If handler throws an error, connect will be rejected. You can set headers that will be sent to client with accept message.

## Multiple handlers
You can set as many handlers for one patter as you need to. All responses will be merged into one object and pass into
protocol as one result.

## Regex patterns
In nestjs adapters you can pass only string as pattern into SubscribeMessage decorator. All messages
checks using strict equal.
This adapter supports string and regex for searching handlers which will be called.

## Gateway namespaces
You can specify namespaces for your gateway. How do they work depends on protocol. See more information in API Reference.

# API Reference:

## Adapter

### Base usage:

```ts
const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app));

await app.listenAsync(3000);
```

### Formatter
You can pass formatter in options in first argument.

```ts
const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app, {
    formatter: new JsonFormat(),
}));

await app.listenAsync(3000);
```

JsonFormat is builtin formatter.

You can write your own formatter for example for yml.

For do this you will extend BaseFormat class and
implement to methods: **parse** and **format**.


## Protocol
You can use protocol like formatter. It can be passed in options in second argument.

```ts
const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app, {
    protocol: new JsonRpcProtocol(),
}));

await app.listenAsync(3000);
```

JsonRpcProtocol is builtin protocol. 

You can write your own protocol handler.

For do this you will extend BaseProtocol class and implement
to methods: **handle** and **formatEvent**.

These methods are not so simple as **parse** and **format** in a formatter,
but BaseProtocol class provides some helpful methods.
You also can use JsonRpcProtocol class as example for your own implementation.

### Namespace delimiter
If you want to use namespaces, you can specify a delimiter between namespaces and method.

```ts
const app = await NestFactory.create(AppModule);

app.useWebsocketAdapter(new WebsocketAdapter(app, {
    namespaceDelimiter: '/',
}));

await app.listenAsync(3000);
```

## Gateways

### WebSocketGateway Decorator
This adapter support WebSocketGateway arguments.
NestJS use first argument as port if it's a number else it will be used as options.
If you pass a port, you can pass options in second argument.

# TODO: Work In Progress