npm package: @gigachatpl/action-based-websocket
Description: ActionBasedWebSocket is a class that wraps WebSocket (default browser WebSocket or from the [WS](https://www.npmjs.com/package//ws) library) and communicates with the server using JSON, making it easier to work with. The class allows for authorization, au
Author: bukaj
Latest version: 1.1.6

ActionBasedWebSocket is a class that wraps WebSocket (default browser WebSocket or from the [WS](https://www.npmjs.com/package//ws) library) and communicates with the server using JSON, making it easier to work with. The class allows for authorization, automatic server reconnection, and communication based on actions.

# ActionBasedWebSocket

ActionBasedWebSocket requires three types to work:

### Action
An enum that contains action names, which are equivalent to event names in JavaScript.

```TypeScript
enum action {
    GET_DATA = "get",
    SEND_DATA = "send"
}
```
### Receiving types
This interface maps action names to the types received from these actions.

```TypeScript
interface MapGivenType {
    [action.GET_DATA]: { usernames: string[] };
}
```

### Sending types 
This interface maps action names to the types sent from these actions.

```TypeScript
interface MapSendType {
    [action.SEND_DATA]: { newData: number };
}
```
### Creation
The constructor requires one of three types of objects. They share the same variables but have different configurations depending on the situation. For example, you don't need a connection address if you've already provided a ready WebSocket.

- websocket -> WebSocket object (from the browser or WSToBrowser, which is part of this package).
- websocketConstructor -> The class to be used to create a WebSocket.
- address -> The address to which the WebSocket should connect.
- onLostConnection -> Callback executed when the connection is lost.
- onReconnected -> Callback executed when the connection is reestablished.
- onAuthSuccess -> Callback is only stored.
- onAuthFail -> Callback is only stored.
- is_reconnect -> Indicates whether the WebSocket connection should be re-established in case of loss. Default is `false`.
- actionWithoutAuthorization -> Array of actions that can be executed without authorization.
- actionBasedServer -> an instance of actionBasedServer that hosts a websocket.
Example:

```TypeScript
new ActionBasedWebSocket<action, MapGivenType, MapSendType>({ websocket: new Websocket("ws:localhost:3000") })
```

### Method: log 
The entire class uses the log method for logging, which by default uses console.log().

### Method: oninit
The oninit method is executed at the beginning of the constructor. It's initially empty (only logs that it's executed). <br>
It can be used, for example, to override properties by a inheriting class before the rest of the constructor is executed.

### Method: oncreate
The oncreate method is executed at the beginning of the constructor after the oninit method. It's initially empty (only logs that it's executed).
<br> It can be used, for example, to set up responseHandlers.

### Method: onopen
It is set as the onopen property of the WebSocket. Additionally, if a ready WebSocket was passed to the constructor, the onopen method will be executed in the constructor.
It's initially empty (only logs that it's executed).
### Method: send
Sends an action.

- action -> The action name.
- params -> Data to be sent. Type checking is performed based on the previously specified types.
- onsuccess -> Callback executed when a response without errors is received. The first parameter is an object of the type defined in the previously specified types.
- onerror -> Callback executed when an error response is received.
### Method: addResponseHandler
Allows adding a responseHandler, similar to using addEventListener in JavaScript. If a specific action is received, the provided callback is executed.

- action -> The action name.
- fun -> The callback to be executed for the specified action. It performs type checking for both parameters and return values. The value returned in the callback will be sent as a response.
Example:

```TypeScript
actionBasedWebSocket.addResponseHandler(action.ADD_ONE, (params) => {
    return { result: params.number + 1 };
})
```
The method returns a function that can be used later to remove the responseHandler.

### Method: removeResponseHandler
Removes a specific callback from the responseHandler.

- action -> The action name.
- fun -> The function returned from addResponseHandler.
removeAllResponseHandlers: Removes all callbacks for a specific action.
- action -> The action name.

### Authorization
The default connected WebSocket is not authorized. This means that any action that comes in (except those listed in actionWithoutAuthorization) will result in an authorization error. To authorize all actions, you should use the `authorizeAllRequests` method. This allows, for example, to expose one action for logging in, while the rest will only be accessible after logging in.

### Error Handling
If an error occurs during the execution of a action's callback, the recipient will receive an "Internal Error" message. <br>
An exception is the `PublicError` class from this package, which allows sending error messages to the recipient. In this case, the error handling callback will be triggered.

`PublicError` takes two parameters: the error message and the error code.

Example:

```TypeScript
throw new PublicError("Data is incorrect", 402);
```

# ActionBasedServer
This is a class that inherits from WebSocketServer [WS](https://www.npmjs.com/package//ws). It adds methods for sending actions to clients.

### Method: registerClient
Allows registering a client under a specific ID.

### Method: unregisterClient
Allows unregistering a client with a given ID.

### Method: broadcast
Enables broadcasting actions to clients registered under a specific ID.

# WSToBrowser
Although the [WS](https://www.npmjs.com/package//ws)  library is based on the browser's WebSocket, it has a slight difference in the send method. This class, which inherits WebSocket from [WS](https://www.npmjs.com/package//ws), eliminates this difference. The rest remains unchanged, and you can use it just like WebSocket from [WS](https://www.npmjs.com/package//ws) .