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(
|
34 | await client.call('method', [1, 2, 3])
|
35 | )
|
36 |
|
37 | await client.close()
|
38 | }
|
39 |
|
40 | // Run the main function and prints any errors.
|
41 | main().catch(error => {
|
42 | console.error(error)
|
43 | process.exit(1)
|
44 | })
|
45 | ```
|
46 |
|
47 | ### Creation
|
48 |
|
49 | ```js
|
50 | const client = new Client(opts)
|
51 | ```
|
52 |
|
53 | `opts` is either a string (the URL of the server) or an object with
|
54 | the following properties:
|
55 |
|
56 | - `url`: URL of the JSON-RPC server
|
57 | - `protocols` (*optional*): the WebSocket sub-protocols to use
|
58 |
|
59 | ### Connection management
|
60 |
|
61 | **Status**
|
62 |
|
63 | ```js
|
64 | console.log(client.status)
|
65 | ```
|
66 |
|
67 | Possible values:
|
68 |
|
69 | - `open`
|
70 | - `connecting`
|
71 | - `closed`
|
72 |
|
73 | **Connection**
|
74 |
|
75 | ```js
|
76 | await client.open()
|
77 | ```
|
78 |
|
79 | **Disconnection**
|
80 |
|
81 | ```js
|
82 | await client.close()
|
83 | ```
|
84 |
|
85 | This method can also be used to abort the connection while connecting.
|
86 |
|
87 | ### Events
|
88 |
|
89 | **Connection**
|
90 |
|
91 | ```js
|
92 | client.on('open', () => {
|
93 | console.log('client is now open')
|
94 | })
|
95 | ```
|
96 |
|
97 | **Disconnection**
|
98 |
|
99 | ```js
|
100 | client.on('closed', () => {
|
101 | console.log('client is now closed')
|
102 | })
|
103 | ```
|
104 |
|
105 | **Notification**
|
106 |
|
107 | ```js
|
108 | client.on('notification', notification => {
|
109 | console.log('notification received', notification)
|
110 | })
|
111 | ```
|
112 |
|
113 | ## Recipes
|
114 |
|
115 | ### Always stay connected
|
116 |
|
117 | > Reconnect on disconnection:
|
118 |
|
119 | ```js
|
120 | client.on('closed', () => {
|
121 | client.open()
|
122 | })
|
123 | ```
|
124 |
|
125 | > Use back off to keep retrying to connect:
|
126 |
|
127 | ```js
|
128 | import { createBackoff } from 'jsonrpc-websocket-client'
|
129 |
|
130 | client.open(createBackoff())
|
131 | ```
|
132 |
|
133 | ## Development
|
134 |
|
135 | ```
|
136 | # Install dependencies
|
137 | > yarn
|
138 |
|
139 | # Run the tests
|
140 | > yarn test
|
141 |
|
142 | # Continuously compile
|
143 | > yarn dev
|
144 |
|
145 | # Continuously run the tests
|
146 | > yarn dev-test
|
147 |
|
148 | # Build for production (automatically called by npm install)
|
149 | > yarn build
|
150 | ```
|
151 |
|
152 | ## Contributions
|
153 |
|
154 | Contributions are *very* welcomed, either on the documentation or on
|
155 | the code.
|
156 |
|
157 | You may:
|
158 |
|
159 | - report any [issue](https://github.com/JsCommunity/jsonrpc-websocket-client/issues)
|
160 | you've encountered;
|
161 | - fork and create a pull request.
|
162 |
|
163 | ## License
|
164 |
|
165 | ISC © [Julien Fontanet](https://julien.isonoe.net)
|