1 | # jsonrpc-websocket-client [![Build Status](https://travis-ci.org/jsonrpc-websocket-client.png?branch=master)](https://travis-ci.org/jsonrpc-websocket-client)
|
2 |
|
3 | > JSON-RPC 2 over WebSocket
|
4 |
|
5 | ## Install
|
6 |
|
7 | Installation of the [npm package](https://npmjs.org/package/jsonrpc-websocket-client):
|
8 |
|
9 | ```
|
10 | > npm install --save jsonrpc-websocket-client
|
11 | ```
|
12 |
|
13 | This library requires promises support, for Node versions prior to 0.12 [see
|
14 | this page](https://github.com/JsCommunity/promise-toolbox#usage) to
|
15 | enable them.
|
16 |
|
17 | ## Usage
|
18 |
|
19 | ```javascript
|
20 | import Client from "jsonrpc-websocket-client";
|
21 |
|
22 | async function main() {
|
23 | const client = new Client("ws://example.org");
|
24 |
|
25 | console.log(client.status);
|
26 | // → closed
|
27 |
|
28 | await client.open();
|
29 |
|
30 | console.log(client.status);
|
31 | // → open
|
32 |
|
33 | console.log(await client.call("method", [1, 2, 3]));
|
34 |
|
35 | await client.close();
|
36 | }
|
37 |
|
38 | // Run the main function and prints any errors.
|
39 | main().catch(error => {
|
40 | console.error(error);
|
41 | process.exit(1);
|
42 | });
|
43 | ```
|
44 |
|
45 | ### Creation
|
46 |
|
47 | ```js
|
48 | const client = new Client(opts);
|
49 | ```
|
50 |
|
51 | `opts` is either a string (the URL of the server) or an object with
|
52 | the following properties:
|
53 |
|
54 | - `url`: URL of the JSON-RPC server
|
55 | - `protocols` (_optional_): the WebSocket sub-protocols to use
|
56 |
|
57 | ### Connection management
|
58 |
|
59 | **Status**
|
60 |
|
61 | ```js
|
62 | console.log(client.status);
|
63 | ```
|
64 |
|
65 | Possible values:
|
66 |
|
67 | - `open`
|
68 | - `connecting`
|
69 | - `closed`
|
70 |
|
71 | **Connection**
|
72 |
|
73 | ```js
|
74 | await client.open();
|
75 | ```
|
76 |
|
77 | **Disconnection**
|
78 |
|
79 | ```js
|
80 | await client.close();
|
81 | ```
|
82 |
|
83 | This method can also be used to abort the connection while connecting.
|
84 |
|
85 | ### Events
|
86 |
|
87 | **Connection**
|
88 |
|
89 | ```js
|
90 | client.on("open", () => {
|
91 | console.log("client is now open");
|
92 | });
|
93 | ```
|
94 |
|
95 | **Disconnection**
|
96 |
|
97 | ```js
|
98 | client.on("closed", () => {
|
99 | console.log("client is now closed");
|
100 | });
|
101 | ```
|
102 |
|
103 | **Notification**
|
104 |
|
105 | ```js
|
106 | client.on("notification", notification => {
|
107 | console.log("notification received", notification);
|
108 | });
|
109 | ```
|
110 |
|
111 | ## Recipes
|
112 |
|
113 | ### Always stay connected
|
114 |
|
115 | > Reconnect on disconnection:
|
116 |
|
117 | ```js
|
118 | client.on("closed", () => {
|
119 | client.open();
|
120 | });
|
121 | ```
|
122 |
|
123 | > Use back off to keep retrying to connect:
|
124 |
|
125 | ```js
|
126 | import { createBackoff } from "jsonrpc-websocket-client";
|
127 |
|
128 | client.open(createBackoff());
|
129 | ```
|
130 |
|
131 | ## Development
|
132 |
|
133 | ```
|
134 | # Install dependencies
|
135 | > yarn
|
136 |
|
137 | # Run the tests
|
138 | > yarn test
|
139 |
|
140 | # Continuously compile
|
141 | > yarn dev
|
142 |
|
143 | # Continuously run the tests
|
144 | > yarn dev-test
|
145 |
|
146 | # Build for production (automatically called by npm install)
|
147 | > yarn build
|
148 | ```
|
149 |
|
150 | ## Contributions
|
151 |
|
152 | Contributions are _very_ welcomed, either on the documentation or on
|
153 | the code.
|
154 |
|
155 | You may:
|
156 |
|
157 | - report any [issue](https://github.com/JsCommunity/jsonrpc-websocket-client/issues)
|
158 | you've encountered;
|
159 | - fork and create a pull request.
|
160 |
|
161 | ## License
|
162 |
|
163 | ISC © [Julien Fontanet](https://julien.isonoe.net)
|