new Client(url, optionsopt)
Creates a client.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
url |
string | WebSocket connection url. |
|
options |
Client.SocketOptions |
<optional> |
Socket options. |
Fires:
Extends
- EventEmitter
Classes
Members
(readonly) id :number
Client id. Server-side only.
Type:
- number
(readonly) connected :boolean
If true, then a client is connected.
Type:
- boolean
(readonly) terminated :boolean
If true, then a client was closed via a close method or an auth error occurred.
Type:
- boolean
(readonly) socket :WebSocket
Underlying websocket.
Type:
- WebSocket
Methods
send(event, …argsopt) → {Promise.<undefined>}
Send an event, no reply. Use on or once methods
to listen events on a recipient side. Reserved event names
(MUST NOT be used): connect, close, open, error,
ping, pong, retry.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
string | Event name. |
|
args |
* |
<optional> <repeatable> |
Arguments. |
Returns:
Resolves when a data has been sent.
- Type
- Promise.<undefined>
sendEncoded(data) → {Promise.<undefined>}
Send a message encoded by Client#encodeMessage or Server#encodeMessage, useful for identical messages
broadcasting.
Parameters:
| Name | Type | Description |
|---|---|---|
data |
Object | Result of |
Returns:
Resolves when a data has been sent.
- Type
- Promise.<undefined>
encodeMessage(event, …argsopt) → {Object}
Encode a message for a later use with Client#sendEncoded.
Reserved event names (MUST NOT be used): connect, close,
open, error, ping, pong, retry.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
string | Event name. |
|
args |
* |
<optional> <repeatable> |
Arguments. |
Returns:
Encoded message.
- Type
- Object
invoke(name, …argsopt) → {Promise.<Object>}
Invoke an RPC procedure. Use Client#register method to
assign an RPC method handler. Reserved procedure names (MUST
NOT be used): connect, close, open, error, ping,
pong, retry.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
name |
string | Procedure name. |
|
args |
* |
<optional> <repeatable> |
Arguments. |
Returns:
Resolves or rejects when a reply is received.
- Type
- Promise.<Object>
register(name, handler)
Register an RPC handler. Each name must have no more than a one
handler, so it throws an error on a duplicate handler
registration attempt. Use Client#invoke to call a method.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string | Procedure name. |
handler |
function | A function that returns a Promise. |
reconnect()
Reconnect. Client-side only.
close(codeopt, stropt, terminateopt)
Closes a client connection.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
code |
number |
<optional> |
1000
|
Code as per WebSocket spec. |
str |
string |
<optional> |
Optional string. |
|
terminate |
boolean |
<optional> |
true
|
Disable reconnect. |
emit()
Alias for Client#send.
emitEncoded()
Alias for Client#sendEncoded.
Type Definitions
Message
Properties:
| Name | Type | Attributes | Description |
|---|---|---|---|
id |
number |
<optional> |
|
name |
string |
<optional> |
|
args |
Array |
<optional> |
|
result |
Object |
<optional> |
|
error |
Object |
<optional> |
General format for all data that is sent or received over a websocket.
Type:
- Object
Encoder(message) → {Promise.<Object>|Object}
Messages encoder. May also return promises for an asynchronous execution.
Parameters:
| Name | Type | Description |
|---|---|---|
message |
Client.Message | Message. |
Returns:
Data to send.
- Type
- Promise.<Object> | Object
Decoder(data) → {Promise.<Client.Message>|Client.Message}
Messages decoder. May also return promises for an asynchronous execution.
Parameters:
| Name | Type | Description |
|---|---|---|
data |
Object | Received data. |
Returns:
Message.
- Type
- Promise.<Client.Message> | Client.Message
ReceiveHook(message) → {Promise.<undefined>|undefined}
Receive hook is run when a client receives a valid message via a websocket. May also return promises for an asynchronous execution.
Parameters:
| Name | Type | Description |
|---|---|---|
message |
Client.Message | Message. |
Returns:
Promise, if it is rejected no handlers will be called.
- Type
- Promise.<undefined> | undefined
SendHook(message, isEncoded) → {Promise.<undefined>|undefined}
Send hook is run when a client sends any message via a websocket. May also return promises for an asynchronous execution.
Parameters:
| Name | Type | Description |
|---|---|---|
message |
Client.Message | Object | Message or object if
|
isEncoded |
boolean | If a message has been already encoded
via |
Returns:
Promise, if it is rejected no handlers will be called.
- Type
- Promise.<undefined> | undefined
RetryConfig
Properties:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
factor |
number |
<optional> |
2
|
|
maxTimeout |
number |
<optional> |
Infinity
|
|
minTimeout |
number |
<optional> |
1000
|
|
randomize |
boolean |
<optional> |
true
|
|
retries |
number |
<optional> |
10
|
Type:
- Object
SocketOptions
Properties:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
ackTimeout |
number |
<optional> |
20000
|
Result wait timeout for
|
auth |
Object |
<optional> |
{}
|
Auth data. |
autoReconnect |
boolean |
<optional> |
true
|
Enable auto reconnect. |
autoReconnectOptions |
Client.RetryConfig |
<optional> |
Auto reconnect config. |
|
binaryType |
string |
<optional> |
'arraybuffer'
|
W3C WebSocket binary data type. |
decoder |
Client.Decoder |
<optional> |
JSON.parse
|
Messages decoder. |
encoder |
Client.Encoder |
<optional> |
JSON.stringify
|
Messages encoder. |
errorFormatter |
function |
<optional> |
String
|
Converter for JS errors to some network format. |
pingInterval |
number |
<optional> |
20000
|
Ping interval in ms. |
pingTimeout |
number |
<optional> |
20000
|
Ping timeout in ms. |
protocols |
string | Array.<string> |
<optional> |
'ws-messaging'
|
WebSocket protocols. |
receiveHook |
Client.ReceiveHook |
<optional> |
Receive hook. |
|
rendHook |
Client.SendHook |
<optional> |
Send hook. |
|
skipValidation |
boolean |
<optional> |
false
|
Skips build-in messages validation. |
WebSocket |
Object |
<optional> |
Alternative websocket constructor, if it is undefined then a global WebSocket is used. |
|
w3c |
boolean |
<optional> |
If WebSocket is using a w3c
send API, or a ws one (from Node.js server implementation with a
callback). By default if a global value is used, then it is |
|
wsOptions |
Object |
<optional> |
Additional options to pass to ws socket constructor. |
Type:
- Object
Events
preprocessingError
Emitted when the other side failed to decode or validate a
websocket message, namely an error is occurred inside either
decoder or receiveHook.
Parameters:
| Name | Type | Description |
|---|---|---|
error |
Object | Converted error. |
open
Emits w3c onopen WebSocket events.
error
Emits w3c onerror WebSocket events. Does not throw if there are no listeners.
Parameters:
| Name | Type | Description |
|---|---|---|
error |
Error | Error. |
retry
Emits retry events when auto reconnecting.
Parameters:
| Name | Type | Description |
|---|---|---|
attempt |
number | Attempt number starting from |
close
Emits w3c onclose WebSocket events.
Parameters:
| Name | Type | Description |
|---|---|---|
data |
CloseEvent | Close event data. |
connect
Socket connection is open and client has passed an auth check. Client-side only.
Parameters:
| Name | Type | Description |
|---|---|---|
data |
Object | undefined | Auth reply data. |