Browse Source

doc

master
peter 5 years ago
parent
commit
2bab836faf

+ 27
- 19
docs/classes/_backend_.rpcserver.md View File

@@ -2,6 +2,8 @@
2 2
 
3 3
 # Class: RPCServer <**SubResType**>
4 4
 
5
+A Websocket-server-on-steroids with built-in RPC capabilities
6
+
5 7
 ## Type parameters
6 8
 
7 9
 ▪ **SubResType**
@@ -41,17 +43,19 @@
41 43
 
42 44
 ###  constructor
43 45
 
44
-\+ **new RPCServer**(`port`: number, `exporters`: [Exporter](../interfaces/_interfaces_.exporter.md)‹SubResType›[], `conf`: T.SocketConf): *[RPCServer](_backend_.rpcserver.md)*
46
+\+ **new RPCServer**(`port`: number, `exporters`: [RPCExporter](../interfaces/_interfaces_.rpcexporter.md)‹SubResType›[], `conf`: T.SocketConf): *[RPCServer](_backend_.rpcserver.md)*
45 47
 
46
-Defined in Backend.ts:19
48
+Defined in Backend.ts:22
49
+
50
+**`throws`** On RPC with no name
47 51
 
48 52
 **Parameters:**
49 53
 
50
-Name | Type | Default |
51
------- | ------ | ------ |
52
-`port` | number | - |
53
-`exporters` | [Exporter](../interfaces/_interfaces_.exporter.md)‹SubResType›[] |  [] |
54
-`conf` | T.SocketConf |   {} |
54
+Name | Type | Default | Description |
55
+------ | ------ | ------ | ------ |
56
+`port` | number | - | The port to listen on |
57
+`exporters` | [RPCExporter](../interfaces/_interfaces_.rpcexporter.md)‹SubResType›[] |  [] | A list of [RPCExporter](../interfaces/_interfaces_.rpcexporter.md) to publish |
58
+`conf` | T.SocketConf |   {} | A [SocketConf](../modules/_types_.md#socketconf) object with optional settings  |
55 59
 
56 60
 **Returns:** *[RPCServer](_backend_.rpcserver.md)*
57 61
 
@@ -61,7 +65,7 @@ Name | Type | Default |
61 65
 
62 66
 • **closeHandler**: *T.CloseHandler*
63 67
 
64
-Defined in Backend.ts:17
68
+Defined in Backend.ts:20
65 69
 
66 70
 ___
67 71
 
@@ -69,7 +73,7 @@ ___
69 73
 
70 74
 • **connectionHandler**: *T.ConnectionHandler*
71 75
 
72
-Defined in Backend.ts:19
76
+Defined in Backend.ts:22
73 77
 
74 78
 ___
75 79
 
@@ -77,15 +81,17 @@ ___
77 81
 
78 82
 • **errorHandler**: *T.ErrorHandler*
79 83
 
80
-Defined in Backend.ts:18
84
+Defined in Backend.ts:21
81 85
 
82 86
 ___
83 87
 
84 88
 ### `Private` exporters
85 89
 
86
-• **exporters**: *[Exporter](../interfaces/_interfaces_.exporter.md)‹SubResType›[]*
90
+• **exporters**: *[RPCExporter](../interfaces/_interfaces_.rpcexporter.md)‹SubResType›[]*
91
+
92
+Defined in Backend.ts:32
87 93
 
88
-Defined in Backend.ts:23
94
+A list of [RPCExporter](../interfaces/_interfaces_.rpcexporter.md) to publish
89 95
 
90 96
 ___
91 97
 
@@ -93,7 +99,7 @@ ___
93 99
 
94 100
 • **io**: *any* =  bsock.createServer()
95 101
 
96
-Defined in Backend.ts:15
102
+Defined in Backend.ts:18
97 103
 
98 104
 ___
99 105
 
@@ -101,7 +107,9 @@ ___
101 107
 
102 108
 • **port**: *number*
103 109
 
104
-Defined in Backend.ts:22
110
+Defined in Backend.ts:31
111
+
112
+The port to listen on
105 113
 
106 114
 ___
107 115
 
@@ -109,7 +117,7 @@ ___
109 117
 
110 118
 • **visibility**: *T.Visibility*
111 119
 
112
-Defined in Backend.ts:16
120
+Defined in Backend.ts:19
113 121
 
114 122
 ___
115 123
 
@@ -117,7 +125,7 @@ ___
117 125
 
118 126
 • **ws**: *Server* =  http.createServer()
119 127
 
120
-Defined in Backend.ts:14
128
+Defined in Backend.ts:17
121 129
 
122 130
 ## Methods
123 131
 
@@ -127,7 +135,7 @@ Defined in Backend.ts:14
127 135
 
128 136
 *Implementation of [Destroyable](../interfaces/_interfaces_.destroyable.md)*
129 137
 
130
-Defined in Backend.ts:80
138
+Defined in Backend.ts:89
131 139
 
132 140
 **Returns:** *Promise‹void›*
133 141
 
@@ -137,7 +145,7 @@ ___
137 145
 
138 146
 ▸ **initRPCs**(`socket`: [Socket](../interfaces/_interfaces_.socket.md)): *void*
139 147
 
140
-Defined in Backend.ts:73
148
+Defined in Backend.ts:82
141 149
 
142 150
 **Parameters:**
143 151
 
@@ -153,6 +161,6 @@ ___
153 161
 
154 162
 ▸ **startWebsocket**(): *void*
155 163
 
156
-Defined in Backend.ts:57
164
+Defined in Backend.ts:66
157 165
 
158 166
 **Returns:** *void*

+ 80
- 42
docs/classes/_frontend_.rpcsocket.md View File

@@ -2,6 +2,8 @@
2 2
 
3 3
 # Class: RPCSocket
4 4
 
5
+A websocket-on-steroids with built-in RPC capabilities
6
+
5 7
 ## Hierarchy
6 8
 
7 9
 * **RPCSocket**
@@ -43,15 +45,15 @@
43 45
 
44 46
 \+ **new RPCSocket**(`port`: number, `server`: string, `tls`: boolean): *[RPCSocket](_frontend_.rpcsocket.md)*
45 47
 
46
-Defined in Frontend.ts:15
48
+Defined in Frontend.ts:20
47 49
 
48 50
 **Parameters:**
49 51
 
50
-Name | Type | Default |
51
------- | ------ | ------ |
52
-`port` | number | - |
53
-`server` | string | - |
54
-`tls` | boolean | false |
52
+Name | Type | Default | Description |
53
+------ | ------ | ------ | ------ |
54
+`port` | number | - | Port to connect to |
55
+`server` | string | - | Server address |
56
+`tls` | boolean | false | @default false use TLS  |
55 57
 
56 58
 **Returns:** *[RPCSocket](_frontend_.rpcsocket.md)*
57 59
 
@@ -63,7 +65,9 @@ Name | Type | Default |
63 65
 
64 66
 *Implementation of [Socket](../interfaces/_interfaces_.socket.md).[port](../interfaces/_interfaces_.socket.md#port)*
65 67
 
66
-Defined in Frontend.ts:16
68
+Defined in Frontend.ts:28
69
+
70
+Port to connect to
67 71
 
68 72
 ___
69 73
 
@@ -71,7 +75,9 @@ ___
71 75
 
72 76
 • **server**: *string*
73 77
 
74
-Defined in Frontend.ts:16
78
+Defined in Frontend.ts:28
79
+
80
+Server address
75 81
 
76 82
 ___
77 83
 
@@ -79,7 +85,7 @@ ___
79 85
 
80 86
 • **socket**: *[Socket](../interfaces/_interfaces_.socket.md)*
81 87
 
82
-Defined in Frontend.ts:15
88
+Defined in Frontend.ts:20
83 89
 
84 90
 ___
85 91
 
@@ -87,7 +93,9 @@ ___
87 93
 
88 94
 • **tls**: *boolean*
89 95
 
90
-Defined in Frontend.ts:16
96
+Defined in Frontend.ts:28
97
+
98
+@default false use TLS
91 99
 
92 100
 ## Methods
93 101
 
@@ -95,14 +103,16 @@ Defined in Frontend.ts:16
95 103
 
96 104
 ▸ **call**(`rpcname`: T.Name, ...`args`: T.Any[]): *Promise‹T.Any›*
97 105
 
98
-Defined in Frontend.ts:40
106
+Defined in Frontend.ts:77
107
+
108
+Trigger a hooked handler on the server
99 109
 
100 110
 **Parameters:**
101 111
 
102
-Name | Type |
103
------- | ------ |
104
-`rpcname` | T.Name |
105
-`...args` | T.Any[] |
112
+Name | Type | Description |
113
+------ | ------ | ------ |
114
+`rpcname` | T.Name | The function to call |
115
+`...args` | T.Any[] | other arguments  |
106 116
 
107 117
 **Returns:** *Promise‹T.Any›*
108 118
 
@@ -112,14 +122,16 @@ ___
112 122
 
113 123
 ▸ **callGenerator**(`fnName`: T.Name, `fnArgs`: T.Arg[]): *T.AsyncFunction*
114 124
 
115
-Defined in Frontend.ts:73
125
+Defined in Frontend.ts:126
126
+
127
+Utility [AsyncFunction](../modules/_types_.md#asyncfunction) generator
116 128
 
117 129
 **Parameters:**
118 130
 
119
-Name | Type |
120
------- | ------ |
121
-`fnName` | T.Name |
122
-`fnArgs` | T.Arg[] |
131
+Name | Type | Description |
132
+------ | ------ | ------ |
133
+`fnName` | T.Name | The function name |
134
+`fnArgs` | T.Arg[] | A string-list of parameters  |
123 135
 
124 136
 **Returns:** *T.AsyncFunction*
125 137
 
@@ -131,7 +143,9 @@ ___
131 143
 
132 144
 *Implementation of [Socket](../interfaces/_interfaces_.socket.md)*
133 145
 
134
-Defined in Frontend.ts:36
146
+Defined in Frontend.ts:68
147
+
148
+Closes the socket. It may attempt to reconnect.
135 149
 
136 150
 **Returns:** *void*
137 151
 
@@ -141,7 +155,9 @@ ___
141 155
 
142 156
 ▸ **connect**(): *Promise‹void›*
143 157
 
144
-Defined in Frontend.ts:48
158
+Defined in Frontend.ts:93
159
+
160
+Connects to the server and attaches available RPCs to this object
145 161
 
146 162
 **Returns:** *Promise‹void›*
147 163
 
@@ -153,7 +169,9 @@ ___
153 169
 
154 170
 *Implementation of [Socket](../interfaces/_interfaces_.socket.md)*
155 171
 
156
-Defined in Frontend.ts:32
172
+Defined in Frontend.ts:61
173
+
174
+Destroys the socket
157 175
 
158 176
 **Returns:** *void*
159 177
 
@@ -161,18 +179,20 @@ ___
161 179
 
162 180
 ###  fire
163 181
 
164
-▸ **fire**(`rpcname`: T.Name, ...`args`: T.Any[]): *Promise‹T.Any›*
182
+▸ **fire**(`rpcname`: T.Name, ...`args`: T.Any[]): *Promise‹void›*
183
+
184
+Defined in Frontend.ts:86
165 185
 
166
-Defined in Frontend.ts:44
186
+An alternative to call that does not wait for confirmation and doesn't return a value.
167 187
 
168 188
 **Parameters:**
169 189
 
170
-Name | Type |
171
------- | ------ |
172
-`rpcname` | T.Name |
173
-`...args` | T.Any[] |
190
+Name | Type | Description |
191
+------ | ------ | ------ |
192
+`rpcname` | T.Name | The function to call |
193
+`...args` | T.Any[] | other arguments  |
174 194
 
175
-**Returns:** *Promise‹T.Any›*
195
+**Returns:** *Promise‹void›*
176 196
 
177 197
 ___
178 198
 
@@ -180,14 +200,20 @@ ___
180 200
 
181 201
 ▸ **hook**(`name`: T.Name, `handler`: function): *[Socket](../interfaces/_interfaces_.socket.md)*
182 202
 
183
-Defined in Frontend.ts:20
203
+Defined in Frontend.ts:37
204
+
205
+Hooks a handler to a function name. Use [call](_frontend_.rpcsocket.md#call) to trigger it.
184 206
 
185 207
 **Parameters:**
186 208
 
187 209
 ▪ **name**: *T.Name*
188 210
 
211
+The function name to listen on
212
+
189 213
 ▪ **handler**: *function*
190 214
 
215
+The handler to attach
216
+
191 217
 ▸ (...`args`: any[]): *any | Promise‹any›*
192 218
 
193 219
 **Parameters:**
@@ -204,14 +230,16 @@ ___
204 230
 
205 231
 ▸ **hookGenerator**(`fnName`: T.Name, `fnArgs`: T.Arg[]): *T.HookFunction*
206 232
 
207
-Defined in Frontend.ts:79
233
+Defined in Frontend.ts:137
234
+
235
+Utility [HookFunction](../modules/_types_.md#hookfunction) generator
208 236
 
209 237
 **Parameters:**
210 238
 
211
-Name | Type |
212
------- | ------ |
213
-`fnName` | T.Name |
214
-`fnArgs` | T.Arg[] |
239
+Name | Type | Description |
240
+------ | ------ | ------ |
241
+`fnName` | T.Name | The function name |
242
+`fnArgs` | T.Arg[] | A string-list of parameters  |
215 243
 
216 244
 **Returns:** *T.HookFunction*
217 245
 
@@ -221,7 +249,9 @@ ___
221 249
 
222 250
 ▸ **info**(): *Promise‹any›*
223 251
 
224
-Defined in Frontend.ts:69
252
+Defined in Frontend.ts:117
253
+
254
+Get a list of available RPCs from the server
225 255
 
226 256
 **Returns:** *Promise‹any›*
227 257
 
@@ -231,14 +261,20 @@ ___
231 261
 
232 262
 ▸ **on**(`type`: "error" | "close", `f`: function): *[Socket](../interfaces/_interfaces_.socket.md)*
233 263
 
234
-Defined in Frontend.ts:28
264
+Defined in Frontend.ts:54
265
+
266
+Attach a listener to error or close events
235 267
 
236 268
 **Parameters:**
237 269
 
238 270
 ▪ **type**: *"error" | "close"*
239 271
 
272
+'error' or 'close'
273
+
240 274
 ▪ **f**: *function*
241 275
 
276
+The listener to attach
277
+
242 278
 ▸ (`e?`: any): *void*
243 279
 
244 280
 **Parameters:**
@@ -255,12 +291,14 @@ ___
255 291
 
256 292
 ▸ **unhook**(`name`: T.Name): *[Socket](../interfaces/_interfaces_.socket.md)*
257 293
 
258
-Defined in Frontend.ts:24
294
+Defined in Frontend.ts:45
295
+
296
+Removes a [hook](_frontend_.rpcsocket.md#hook) listener by name.
259 297
 
260 298
 **Parameters:**
261 299
 
262
-Name | Type |
263
------- | ------ |
264
-`name` | T.Name |
300
+Name | Type | Description |
301
+------ | ------ | ------ |
302
+`name` | T.Name | The function name  |
265 303
 
266 304
 **Returns:** *[Socket](../interfaces/_interfaces_.socket.md)*

+ 1
- 1
docs/interfaces/_interfaces_.destroyable.md View File

@@ -24,6 +24,6 @@
24 24
 
25 25
 ▸ **destroy**(): *void*
26 26
 
27
-Defined in Interfaces.ts:20
27
+Defined in Interfaces.ts:26
28 28
 
29 29
 **Returns:** *void*

+ 0
- 39
docs/interfaces/_interfaces_.exporter.md View File

@@ -1,39 +0,0 @@
1
-[rpclibrary](../README.md) › [Globals](../globals.md) › ["Interfaces"](../modules/_interfaces_.md) › [Exporter](_interfaces_.exporter.md)
2
-
3
-# Interface: Exporter <**T**>
4
-
5
-## Type parameters
6
-
7
-▪ **T**
8
-
9
-## Hierarchy
10
-
11
-* **Exporter**
12
-
13
-## Index
14
-
15
-### Properties
16
-
17
-* [name](_interfaces_.exporter.md#name)
18
-
19
-### Methods
20
-
21
-* [exportRPCs](_interfaces_.exporter.md#exportrpcs)
22
-
23
-## Properties
24
-
25
-###  name
26
-
27
-• **name**: *T.Name*
28
-
29
-Defined in Interfaces.ts:5
30
-
31
-## Methods
32
-
33
-###  exportRPCs
34
-
35
-▸ **exportRPCs**(): *T.RPC‹T›[]*
36
-
37
-Defined in Interfaces.ts:6
38
-
39
-**Returns:** *T.RPC‹T›[]*

+ 10
- 8
docs/interfaces/_interfaces_.socket.md View File

@@ -2,6 +2,8 @@
2 2
 
3 3
 # Interface: Socket
4 4
 
5
+Generic socket interface that can apply to bsock as well as RPCSocket
6
+
5 7
 ## Hierarchy
6 8
 
7 9
 * [Destroyable](_interfaces_.destroyable.md)
@@ -34,7 +36,7 @@
34 36
 
35 37
 • **call**: *function*
36 38
 
37
-Defined in Interfaces.ts:13
39
+Defined in Interfaces.ts:19
38 40
 
39 41
 #### Type declaration:
40 42
 
@@ -53,7 +55,7 @@ ___
53 55
 
54 56
 • **fire**: *function*
55 57
 
56
-Defined in Interfaces.ts:14
58
+Defined in Interfaces.ts:20
57 59
 
58 60
 #### Type declaration:
59 61
 
@@ -72,7 +74,7 @@ ___
72 74
 
73 75
 • **hook**: *function*
74 76
 
75
-Defined in Interfaces.ts:11
77
+Defined in Interfaces.ts:17
76 78
 
77 79
 #### Type declaration:
78 80
 
@@ -98,7 +100,7 @@ ___
98 100
 
99 101
 • **on**: *T.OnFunction*
100 102
 
101
-Defined in Interfaces.ts:15
103
+Defined in Interfaces.ts:21
102 104
 
103 105
 ___
104 106
 
@@ -106,7 +108,7 @@ ___
106 108
 
107 109
 • **port**: *number*
108 110
 
109
-Defined in Interfaces.ts:10
111
+Defined in Interfaces.ts:16
110 112
 
111 113
 ___
112 114
 
@@ -114,7 +116,7 @@ ___
114 116
 
115 117
 • **unhook**: *function*
116 118
 
117
-Defined in Interfaces.ts:12
119
+Defined in Interfaces.ts:18
118 120
 
119 121
 #### Type declaration:
120 122
 
@@ -132,7 +134,7 @@ Name | Type |
132 134
 
133 135
 ▸ **close**(): *void*
134 136
 
135
-Defined in Interfaces.ts:16
137
+Defined in Interfaces.ts:22
136 138
 
137 139
 **Returns:** *void*
138 140
 
@@ -144,6 +146,6 @@ ___
144 146
 
145 147
 *Inherited from [Destroyable](_interfaces_.destroyable.md).[destroy](_interfaces_.destroyable.md#destroy)*
146 148
 
147
-Defined in Interfaces.ts:20
149
+Defined in Interfaces.ts:26
148 150
 
149 151
 **Returns:** *void*

+ 6
- 4
docs/modules/_frontend_.md View File

@@ -18,12 +18,14 @@
18 18
 
19 19
 ▸ **stripAfterEquals**(`str`: string): *string*
20 20
 
21
-Defined in Frontend.ts:9
21
+Defined in Frontend.ts:12
22
+
23
+Utility function to strip parameters like "a = 3" of their defaults
22 24
 
23 25
 **Parameters:**
24 26
 
25
-Name | Type |
26
------- | ------ |
27
-`str` | string |
27
+Name | Type | Description |
28
+------ | ------ | ------ |
29
+`str` | string | The parameter to modify  |
28 30
 
29 31
 **Returns:** *string*

+ 1
- 1
docs/modules/_interfaces_.md View File

@@ -7,5 +7,5 @@
7 7
 ### Interfaces
8 8
 
9 9
 * [Destroyable](../interfaces/_interfaces_.destroyable.md)
10
-* [Exporter](../interfaces/_interfaces_.exporter.md)
10
+* [RPCExporter](../interfaces/_interfaces_.rpcexporter.md)
11 11
 * [Socket](../interfaces/_interfaces_.socket.md)

+ 23
- 15
docs/modules/_utils_.md View File

@@ -18,13 +18,15 @@
18 18
 
19 19
 ▸ **extractArgs**(`f`: Function): *T.Arg[]*
20 20
 
21
-Defined in Utils.ts:102
21
+Defined in Utils.ts:110
22
+
23
+Extract a string list of parameters from a function
22 24
 
23 25
 **Parameters:**
24 26
 
25
-Name | Type |
26
------- | ------ |
27
-`f` | Function |
27
+Name | Type | Description |
28
+------ | ------ | ------ |
29
+`f` | Function | The source function  |
28 30
 
29 31
 **Returns:** *T.Arg[]*
30 32
 
@@ -34,16 +36,20 @@ ___
34 36
 
35 37
 ▸ **hookGenerator**(`rpc`: T.HookRPC‹any›): *function*
36 38
 
37
-Defined in Utils.ts:81
39
+Defined in Utils.ts:85
40
+
41
+Utility function to generate [HookFunction](_types_.md#hookfunction) from a RPC
38 42
 
39 43
 **Parameters:**
40 44
 
41
-Name | Type |
42
------- | ------ |
43
-`rpc` | T.HookRPC‹any› |
45
+Name | Type | Description |
46
+------ | ------ | ------ |
47
+`rpc` | T.HookRPC‹any› | The RPC to transform |
44 48
 
45 49
 **Returns:** *function*
46 50
 
51
+A [HookFunction](_types_.md#hookfunction)
52
+
47 53
 ▸ (`socket?`: I.Socket): *[HookFunction](_types_.md#hookfunction)‹T›*
48 54
 
49 55
 **Parameters:**
@@ -58,13 +64,15 @@ ___
58 64
 
59 65
 ▸ **makeSubResponse**(`uuid?`: undefined | string): *[SubscriptionResponse](_types_.md#subscriptionresponse)*
60 66
 
61
-Defined in Utils.ts:107
67
+Defined in Utils.ts:119
68
+
69
+Simple utility function to create basic [SubscriptionResponse](_types_.md#subscriptionresponse)
62 70
 
63 71
 **Parameters:**
64 72
 
65
-Name | Type |
66
------- | ------ |
67
-`uuid?` | undefined &#124; string |
73
+Name | Type | Description |
74
+------ | ------ | ------ |
75
+`uuid?` | undefined &#124; string | optional uuid to use, otherwise defaults to uuid/v4  |
68 76
 
69 77
 **Returns:** *[SubscriptionResponse](_types_.md#subscriptionresponse)*
70 78
 
@@ -72,11 +80,11 @@ ___
72 80
 
73 81
 ###  rpcHooker
74 82
 
75
-▸ **rpcHooker**<**SubResT**>(`socket`: [Socket](../interfaces/_interfaces_.socket.md), `exporter`: [Exporter](../interfaces/_interfaces_.exporter.md)‹SubResT›, `makeUnique`: boolean): *T.ExtendedRpcInfo[]*
83
+▸ **rpcHooker**<**SubResT**>(`socket`: [Socket](../interfaces/_interfaces_.socket.md), `exporter`: [RPCExporter](../interfaces/_interfaces_.rpcexporter.md)‹SubResT›, `makeUnique`: boolean): *T.ExtendedRpcInfo[]*
76 84
 
77 85
 Defined in Utils.ts:59
78 86
 
79
-Utility function to apply the RPCs of an [Exporter](../interfaces/_interfaces_.exporter.md).
87
+Utility function to apply the RPCs of an [RPCExporter](../interfaces/_interfaces_.rpcexporter.md).
80 88
 
81 89
 **Type parameters:**
82 90
 
@@ -87,7 +95,7 @@ Utility function to apply the RPCs of an [Exporter](../interfaces/_interfaces_.e
87 95
 Name | Type | Default | Description |
88 96
 ------ | ------ | ------ | ------ |
89 97
 `socket` | [Socket](../interfaces/_interfaces_.socket.md) | - | The websocket (implementation: bsock) to hook on |
90
-`exporter` | [Exporter](../interfaces/_interfaces_.exporter.md)‹SubResT› | - | The exporter |
98
+`exporter` | [RPCExporter](../interfaces/_interfaces_.rpcexporter.md)‹SubResT› | - | The exporter |
91 99
 `makeUnique` | boolean | true | @default true Attach a suffix to RPC names  |
92 100
 
93 101
 **Returns:** *T.ExtendedRpcInfo[]*

+ 10
- 1
src/Backend.ts View File

@@ -7,6 +7,9 @@ import * as T from './Types';
7 7
 import * as U from './Utils'; 
8 8
 import * as I from './Interfaces';
9 9
 
10
+/**
11
+ * A Websocket-server-on-steroids with built-in RPC capabilities
12
+ */
10 13
 export class RPCServer<
11 14
     SubResType = {}
12 15
 > implements I.Destroyable{
@@ -18,9 +21,15 @@ export class RPCServer<
18 21
     private errorHandler: T.ErrorHandler
19 22
     private connectionHandler: T.ConnectionHandler
20 23
 
24
+    /**
25
+     * @throws On RPC with no name
26
+     * @param port The port to listen on
27
+     * @param exporters A list of {@link RPCExporter} to publish
28
+     * @param conf A {@link SocketConf} object with optional settings
29
+     */
21 30
     constructor(
22 31
         private port:number,
23
-        private exporters: I.Exporter<SubResType>[] = [],
32
+        private exporters: I.RPCExporter<SubResType>[] = [],
24 33
         conf: T.SocketConf =  {}
25 34
     ){
26 35
         

+ 63
- 5
src/Frontend.ts View File

@@ -5,46 +5,91 @@ import bsock = require('bsock');
5 5
 import * as T from './Types'; 
6 6
 import * as I from './Interfaces';
7 7
 
8
-//fix args with defaults like "force = true" -> "force"
9
-function stripAfterEquals(str:string){
8
+/**
9
+ * Utility function to strip parameters like "a = 3" of their defaults
10
+ * @param str The parameter to modify
11
+ */
12
+function stripAfterEquals(str:string):string{
10 13
     return str.split("=")[0]
11 14
 }
12 15
 
16
+/**
17
+ * A websocket-on-steroids with built-in RPC capabilities
18
+ */
13 19
 export class RPCSocket implements I.Socket{
14
-
15 20
     private socket: I.Socket
21
+
22
+    /**
23
+     * 
24
+     * @param port Port to connect to
25
+     * @param server Server address
26
+     * @param tls @default false use TLS
27
+     */
16 28
     constructor(public port:number, private server: string, private tls: boolean = false){
17 29
         Object.defineProperty(this, 'socket', {value: undefined, writable: true})
18 30
     }
19 31
 
32
+    /**
33
+     * Hooks a handler to a function name. Use {@link call} to trigger it.
34
+     * @param name The function name to listen on
35
+     * @param handler The handler to attach
36
+     */
20 37
     public hook(name: T.Name, handler: (...args:any[]) => any | Promise<any>){
21 38
         return this.socket.hook(name, handler)
22 39
     }
23 40
 
41
+    /**
42
+     * Removes a {@link hook} listener by name.
43
+     * @param name The function name 
44
+     */
24 45
     public unhook(name: T.Name){
25 46
         return this.socket.unhook(name)
26 47
     }
27 48
 
49
+    /**
50
+     * Attach a listener to error or close events
51
+     * @param type 'error' or 'close'
52
+     * @param f The listener to attach
53
+     */
28 54
     public on(type: "error" | "close", f: (e?: any) => void){
29 55
         return this.socket.on(type, f)
30 56
     }
31 57
 
58
+    /**
59
+     * Destroys the socket
60
+     */
32 61
     public destroy(){
33 62
         return this.socket.destroy()
34 63
     }
35 64
 
65
+    /**
66
+     * Closes the socket. It may attempt to reconnect.
67
+     */
36 68
     public close(){
37 69
         return this.socket.close()
38 70
     }
39 71
 
72
+    /**
73
+     * Trigger a hooked handler on the server
74
+     * @param rpcname The function to call
75
+     * @param args other arguments
76
+     */
40 77
     public async call (rpcname: T.Name, ...args: T.Any[]) : Promise<T.Any>{
41 78
         return await this.socket.call.apply(this.socket, [rpcname, ...args])
42 79
     }
43 80
 
44
-    public async fire(rpcname: T.Name, ...args: T.Any[]) : Promise<T.Any>{
45
-        return await this.socket.fire.apply(this.socket, [rpcname, ...args])
81
+    /**
82
+     * An alternative to call that does not wait for confirmation and doesn't return a value.
83
+     * @param rpcname The function to call
84
+     * @param args other arguments
85
+     */
86
+    public async fire(rpcname: T.Name, ...args: T.Any[]) : Promise<void>{
87
+        await this.socket.fire.apply(this.socket, [rpcname, ...args])
46 88
     }
47 89
     
90
+    /**
91
+     * Connects to the server and attaches available RPCs to this object
92
+     */
48 93
     public async connect(){
49 94
         this.socket = await bsock.connect(this.port, this.server, this.tls)
50 95
 
@@ -66,16 +111,29 @@ export class RPCSocket implements I.Socket{
66 111
         })
67 112
     }
68 113
 
114
+    /**
115
+     * Get a list of available RPCs from the server
116
+     */
69 117
     public async info(){
70 118
         return await this.socket.call('info')
71 119
     }
72 120
 
121
+    /**
122
+     * Utility {@link AsyncFunction} generator
123
+     * @param fnName The function name
124
+     * @param fnArgs A string-list of parameters
125
+     */
73 126
     private callGenerator(fnName: T.Name, fnArgs:T.Arg[]): T.AsyncFunction{
74 127
         const headerArgs = fnArgs.join(",")
75 128
         const argParams = fnArgs.map(stripAfterEquals).join(",")
76 129
         return eval( '( () => async ('+headerArgs+') => { return await this.socket.call("'+fnName+'", '+argParams+')} )()' )
77 130
     }
78 131
 
132
+    /**
133
+     * Utility {@link HookFunction} generator
134
+     * @param fnName The function name
135
+     * @param fnArgs A string-list of parameters
136
+     */
79 137
     private hookGenerator(fnName: T.Name, fnArgs:T.Arg[]): T.HookFunction{
80 138
         const headerArgs = fnArgs.join(",")
81 139
         const argParams = fnArgs.map(stripAfterEquals).join(",")

+ 7
- 1
src/Interfaces.ts View File

@@ -1,11 +1,17 @@
1 1
 import * as T from "./Types";
2 2
 import * as I from "./Interfaces"
3 3
 
4
-export interface Exporter<T = {}>{
4
+/**
5
+ * Interface for all classes that may export RPCs
6
+ */
7
+export interface RPCExporter<T = {}>{
5 8
     name: T.Name
6 9
     exportRPCs() : T.RPC<T>[]
7 10
 }
8 11
 
12
+/**
13
+ * Generic socket interface that can apply to bsock as well as RPCSocket
14
+ */
9 15
 export interface Socket extends Destroyable {
10 16
     port: number
11 17
     hook: (rpcname: T.Name, handler: (...args:any[]) => any | Promise<any>) => I.Socket

+ 16
- 4
src/Utils.ts View File

@@ -8,7 +8,7 @@ import { SubscriptionResponse } from "./Types";
8 8
  * Translate an RPC to RPCInfo for serialization.
9 9
  * @param rpc The RPC to transform
10 10
  * @param owner The owning RPC group's name
11
- * @throws {Errror} Error on RPC without name property
11
+ * @throws Error on RPC without name property
12 12
  */
13 13
 export const rpcToRpcinfo = <SubResT = {}>(rpc : T.RPC<SubResT>, owner: T.Owner):T.RpcInfo => {
14 14
     switch (typeof rpc){
@@ -51,12 +51,12 @@ RPC did not provide a name.
51 51
 }
52 52
 
53 53
 /**
54
- * Utility function to apply the RPCs of an {@link Exporter}.
54
+ * Utility function to apply the RPCs of an {@link RPCExporter}.
55 55
  * @param socket The websocket (implementation: bsock) to hook on
56 56
  * @param exporter The exporter
57 57
  * @param makeUnique @default true Attach a suffix to RPC names
58 58
  */
59
-export function rpcHooker<SubResT = {}>(socket: I.Socket, exporter:I.Exporter<SubResT>, makeUnique = true):T.ExtendedRpcInfo[]{
59
+export function rpcHooker<SubResT = {}>(socket: I.Socket, exporter:I.RPCExporter<SubResT>, makeUnique = true):T.ExtendedRpcInfo[]{
60 60
     const owner = exporter.name
61 61
     const RPCs = [...exporter.exportRPCs()]
62 62
     const suffix = makeUnique?"-"+uuidv4().substr(0,4):""
@@ -77,7 +77,11 @@ export function rpcHooker<SubResT = {}>(socket: I.Socket, exporter:I.Exporter<Su
77 77
         return ret
78 78
     })
79 79
 }
80
-//
80
+/**
81
+ * Utility function to generate {@link HookFunction} from a RPC
82
+ * @param rpc The RPC to transform
83
+ * @returns A {@link HookFunction}
84
+ */
81 85
 const hookGenerator = (rpc:T.HookRPC<any>): T.HookInfo['generator'] => { 
82 86
     const argsArr = extractArgs(rpc.hook)
83 87
     argsArr.pop()
@@ -99,11 +103,19 @@ const hookGenerator = (rpc:T.HookRPC<any>): T.HookInfo['generator'] => {
99 103
     }`)
100 104
 }
101 105
 
106
+/**
107
+ * Extract a string list of parameters from a function
108
+ * @param f The source function
109
+ */
102 110
 const extractArgs = (f:Function):T.Arg[] => {
103 111
     let fn
104 112
     return (fn = String(f)).substr(0, fn.indexOf(")")).substr(fn.indexOf("(")+1).split(",")
105 113
 }
106 114
 
115
+/**
116
+ * Simple utility function to create basic {@link SubscriptionResponse}
117
+ * @param uuid optional uuid to use, otherwise defaults to uuid/v4
118
+ */
107 119
 export function makeSubResponse(uuid?:string):SubscriptionResponse{
108 120
     return {
109 121
         result: "Success",

Loading…
Cancel
Save