1 | # jsonrpc-websocket-client
|
2 |
|
3 | [![Package Version](https://badgen.net/npm/v/jsonrpc-websocket-client)](https://npmjs.org/package/jsonrpc-websocket-client) [![Build Status](https://travis-ci.org/JsCommunity/jsonrpc-websocket-client.png?branch=master)](https://travis-ci.org/JsCommunity/jsonrpc-websocket-client) [![PackagePhobia](https://badgen.net/packagephobia/install/jsonrpc-websocket-client)](https://packagephobia.now.sh/result?p=jsonrpc-websocket-client) [![Latest Commit](https://badgen.net/github/last-commit/JsCommunity/jsonrpc-websocket-client)](https://github.com/JsCommunity/jsonrpc-websocket-client/commits/master)
|
4 |
|
5 | > JSON-RPC 2 over WebSocket
|
6 |
|
7 | ## Install
|
8 |
|
9 | Installation of the [npm package](https://npmjs.org/package/jsonrpc-websocket-client):
|
10 |
|
11 | ```
|
12 | > npm install --save jsonrpc-websocket-client
|
13 | ```
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```javascript
|
18 | import Client from "jsonrpc-websocket-client";
|
19 |
|
20 | async function main() {
|
21 | const client = new Client("ws://example.org");
|
22 |
|
23 | console.log(client.status);
|
24 | // → closed
|
25 |
|
26 | await client.open();
|
27 |
|
28 | console.log(client.status);
|
29 | // → open
|
30 |
|
31 | console.log(await client.call("method", [1, 2, 3]));
|
32 |
|
33 | await client.close();
|
34 | }
|
35 |
|
36 | // Run the main function and prints any errors.
|
37 | main().catch((error) => {
|
38 | console.error(error);
|
39 | process.exit(1);
|
40 | });
|
41 | ```
|
42 |
|
43 | ### Creation
|
44 |
|
45 | ```js
|
46 | const client = new Client(opts);
|
47 | ```
|
48 |
|
49 | `opts` is either a string (the URL of the server) or an object with
|
50 | the following properties:
|
51 |
|
52 | - `url`: URL of the JSON-RPC server
|
53 | - `protocols` (_optional_): the WebSocket sub-protocols to use
|
54 | - `rejectUnauthorized` (defaults to `true`): whether to reject invalid HTTPS certificate (e.g. self signed)
|
55 |
|
56 | ### Connection management
|
57 |
|
58 | **Status**
|
59 |
|
60 | ```js
|
61 | console.log(client.status);
|
62 | ```
|
63 |
|
64 | Possible values:
|
65 |
|
66 | - `open`
|
67 | - `connecting`
|
68 | - `closed`
|
69 |
|
70 | **Connection**
|
71 |
|
72 | ```js
|
73 | await client.open();
|
74 | ```
|
75 |
|
76 | **Disconnection**
|
77 |
|
78 | ```js
|
79 | await client.close();
|
80 | ```
|
81 |
|
82 | This method can also be used to abort the connection while connecting.
|
83 |
|
84 | ### Events
|
85 |
|
86 | **Connection**
|
87 |
|
88 | ```js
|
89 | client.on("open", () => {
|
90 | console.log("client is now open");
|
91 | });
|
92 | ```
|
93 |
|
94 | **Disconnection**
|
95 |
|
96 | ```js
|
97 | client.on("closed", () => {
|
98 | console.log("client is now closed");
|
99 | });
|
100 | ```
|
101 |
|
102 | **Notification**
|
103 |
|
104 | ```js
|
105 | client.on("notification", (notification) => {
|
106 | console.log("notification received", notification);
|
107 | });
|
108 | ```
|
109 |
|
110 | ## Recipes
|
111 |
|
112 | ### Always stay connected
|
113 |
|
114 | > Reconnect on disconnection:
|
115 |
|
116 | ```js
|
117 | client.on("closed", () => {
|
118 | client.open();
|
119 | });
|
120 | ```
|
121 |
|
122 | > Use back off to keep retrying to connect:
|
123 |
|
124 | ```js
|
125 | import { createBackoff } from "jsonrpc-websocket-client";
|
126 |
|
127 | client.open(createBackoff());
|
128 | ```
|
129 |
|
130 | ## Contributions
|
131 |
|
132 | Contributions are _very_ welcomed, either on the documentation or on
|
133 | the code.
|
134 |
|
135 | You may:
|
136 |
|
137 | - report any [issue](https://github.com/JsCommunity/jsonrpc-websocket-client/issues)
|
138 | you've encountered;
|
139 | - fork and create a pull request.
|
140 |
|
141 | ## License
|
142 |
|
143 | ISC © [Julien Fontanet](https://julien.isonoe.net)
|