You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 21, 2021. It is now read-only.
CORE-1242, CORE-1243, CORE-1244 Webpack and Stream API (#13)
* installed webpack and es6-ified everything
* to make websockets work, use separate builds for node and web
* tweaks for running tests
* delete unused dist files
* add rest endpoint files
* add restUrl option
* works otherwise but fetch is missing from node
* added node-fetch + its shim for browser
* add integration tests, fix bugs
* build
* change author to 'Streamr'
* rename authKey to apiKey in README
* refactor Subscription state, update eslint rules
* Update readme, remove public read permission manipulation as that will become quite redundant after marketplace
* delete files in dist
* dist added to .gitignore
* fix webpack use of this module by adding 'module' field to package.json
* fall back to commonjs modules and drop node build
<!-- Note that this readme is embedded on API Documentation page within Streamr. Please don't use first-level headings (h1). You should write this document so that it will work both as a stand-alone document in the public GitHub repo and as a section in the API docs. -->
2
2
<aname="js-client"></a>
3
-
## Streamr Javascript Client
3
+
## Streamr JavaScript Client
4
4
5
-
By using this client, you can easily subscribe to realtime [Streamr](http://www.streamr.com) streams from Javascript-based environments, such as browsers and [node.js](https://nodejs.org). This enables you to use Streamr as an over-the-internet pub/sub engine with powerful analytics and automation features.
5
+
By using this client, you can easily interact with the [Streamr](http://www.streamr.com) API from JavaScript-based environments, such as browsers and [node.js](https://nodejs.org). You can, for example, subscribe to real-time data in Streams, produce new data to Streams, and create new Streams.
6
+
7
+
This library is work-in-progress and doesn't provide wrapper functions for all the endpoints in the Streamr API. Currently it covers producing and subscribing to data as well as manipulating Stream objects.
6
8
7
9
The client uses websockets for streaming message delivery. It should work in all modern browsers.
8
10
@@ -14,34 +16,69 @@ The client is available on [npm](https://www.npmjs.com/package/streamr-client) a
14
16
15
17
### Usage
16
18
17
-
Here's a quick example. More detailed examples for the browser and node.js can be found [here](https://github.com/streamr-dev/streamr-client/tree/master/examples).
19
+
Here are some quick examples. More detailed examples for the browser and node.js can be found [here](https://github.com/streamr-dev/streamr-client/tree/master/examples).
20
+
21
+
#### Creating a StreamrClient instance
18
22
19
23
```javascript
20
-
// Create a StreamrClient instance
21
24
var client =newStreamrClient({
22
-
// See below for options
25
+
// See below for more options
26
+
apiKey:'your-api-key'
23
27
})
28
+
```
24
29
25
-
// Subscribe to a stream
30
+
#### Subscribing to real-time events in a stream
31
+
32
+
```javascript
26
33
var sub =client.subscribe(
27
34
{
28
35
stream:'streamId',
36
+
apiKey:'secret', // Optional. If not given, uses the apiKey given at client creation time.
29
37
partition:0, // Optional, defaults to zero. Use for partitioned streams to select partition.
30
-
authKey:'authKey'// Optional. If not given, uses the authKey given at client creation time.
31
38
// optional resend options here
32
39
},
33
40
function(message, metadata) {
34
-
// Do something with the message, which is an object
41
+
// This is the message handler which gets called for every incoming message in the Stream.
42
+
// Do something with the message here!
35
43
}
36
44
)
37
45
```
38
46
47
+
#### Programmatically creating a Stream
48
+
49
+
```javascript
50
+
client.getOrCreateStream({
51
+
name:'My awesome Stream created via the API',
52
+
})
53
+
.then((stream) => {
54
+
console.log('Stream '+stream.id+'has been created!')
55
+
// Do something with the Stream
56
+
})
57
+
```
58
+
59
+
#### Producing data points to a Stream
60
+
61
+
```javascript
62
+
// Here's our example data point
63
+
var msg = {
64
+
temperature:25.4,
65
+
humidity:10,
66
+
happy:true
67
+
}
68
+
69
+
// Produce using the Stream id only
70
+
client.produceToStream('my-stream-id', msg)
71
+
72
+
// Or alternatively, via the Stream object (from e.g. getOrCreateStream)
73
+
stream.produce(msg)
74
+
```
75
+
39
76
### Client options
40
77
41
78
Option | Default value | Description
42
79
------ | ------------- | -----------
43
80
url | wss://www.streamr.com/api/v1/ws | Address of the Streamr websocket endpoint to connect to.
44
-
authKey | null | Define default authKey to use when none is specified in the call to `client.subscribe`.
81
+
apiKey | null | Define a default apiKey to use when none is specified in the individual function calls.
45
82
autoConnect | true | If set to `true`, the client connects automatically on the first call to `subscribe()`. Otherwise an explicit call to `connect()` is required.
46
83
autoDisconnect | true | If set to `true`, the client automatically disconnects when the last stream is unsubscribed. Otherwise the connection is left open and can be disconnected explicitly by calling `disconnect()`.
47
84
@@ -54,19 +91,55 @@ Argument | Description
54
91
message | A javascript object containing the message itself
55
92
metadata | Metadata for the message, for example `metadata.timestamp` etc.
56
93
57
-
### Methods
94
+
### StreamrClient object
95
+
96
+
#### Connecting
58
97
59
98
Name | Description
60
99
---- | -----------
61
100
connect() | Connects to the server, and also subscribes to any streams for which `subscribe()` has been called before calling `connect()`.
62
101
disconnect() | Disconnects from the server, clearing all subscriptions.
63
102
pause() | Disconnects from the server without clearing subscriptions.
103
+
104
+
#### Managing subscriptions
105
+
106
+
Name | Description
107
+
---- | -----------
64
108
subscribe(options, callback) | Subscribes to a stream. Messages in this stream are passed to the `callback` function. See below for subscription options. Returns a `Subscription` object.
65
109
unsubscribe(Subscription) | Unsubscribes the given `Subscription`.
66
110
unsubscribeAll(`streamId`) | Unsubscribes all `Subscriptions` for `streamId`.
67
111
getSubscriptions(`streamId`) | Returns a list of `Subscriptions` for `streamId`.
68
-
bind(eventName, function) | Binds a `function` to an event called `eventName`
69
-
unbind(eventName, function) | Unbinds the `function` from events called `eventName`
112
+
113
+
#### Stream API
114
+
115
+
All the below functions return a Promise which gets resolved with the result. They can also take an `apiKey` as an extra argument. Otherwise the `apiKey` defined in the `StreamrClient` options is used, if any.
116
+
117
+
Name | Description
118
+
---- | -----------
119
+
getStream(streamId) | Fetches a Stream object from the API.
120
+
listStreams(query) | Fetches an array of Stream objects from the API. For the query params, consult the API docs.
121
+
getStreamByName(name) | Fetches a Stream which exactly matches the given name.
122
+
createStream(properties) | Creates a Stream with the given properties. For more information on the Stream properties, consult the API docs.
123
+
getOrCreateStream(properties) | Gets a Stream with the id or name given in `properties`, or creates it if one is not found.
124
+
produceToStream(streamId, message) | Produces a new message (data point) to the given Stream.
125
+
126
+
#### Listening to state changes of the client
127
+
128
+
on(eventName, function) | Binds a `function` to an event called `eventName`
129
+
once(eventName, function) | Binds a `function` to an event called `eventName`. It gets called once and then removed.
130
+
removeListener(eventName, function) | Unbinds the `function` from events called `eventName`
131
+
132
+
### Stream object
133
+
134
+
All the below functions return a Promise which gets resolved with the result. They can also take an `apiKey` as an extra argument. Otherwise the `apiKey` defined in the `StreamrClient` options is used, if any.
135
+
136
+
Name | Description
137
+
---- | -----------
138
+
update() | Updates the properties of this Stream object by sending them to the API.
139
+
delete() | Deletes this Stream.
140
+
getPermissions() | Returns the list of permissions for this Stream.
141
+
detectFields() | Updates the Stream field config (schema) to match the latest data point in the Stream.
142
+
produce(message) | Produces a new message (data point) to this Stream.
70
143
71
144
### Subscription options
72
145
@@ -75,7 +148,7 @@ Note that only one of the resend options can be used for a particular subscripti
75
148
Name | Description
76
149
---- | -----------
77
150
stream | Stream id to subscribe to
78
-
authKey | User key or stream key that authorizes the subscription. If defined, overrides the client's `authKey`.
151
+
apiKey | User key or stream key that authorizes the subscription. If defined, overrides the client's `apiKey`.
79
152
partition | Partition number to subscribe to. Defaults to the default partition (0).
80
153
resend_all | Set to `true` if you want all the messages for the stream resent from the earliest available message.
81
154
resend_last | Resend the previous `N` messages.
@@ -85,28 +158,21 @@ resend_to | Can be used in conjunction with `resend_from` to limit the end of th
85
158
86
159
### Binding to events
87
160
88
-
The client and the subscriptions can fire events as detailed below. You can bind to them using `bind`:
161
+
The client and the subscriptions can fire events as detailed below. You can bind to them using `on`:
89
162
90
163
```javascript
91
-
functionhello() {
92
-
console.log('Hello!')
93
-
}
94
-
95
-
client.bind('connected', hello)
164
+
// The StreamrClient emits various events
165
+
client.on('connected', function() {
166
+
console.log('Yeah, we are connected now!')
167
+
})
96
168
169
+
// So does the Subscription object
97
170
var sub =client.subscribe(...)
98
-
sub.bind('subscribed', function() {
171
+
sub.on('subscribed', function() {
99
172
console.log('Subscribed to '+sub.streamId)
100
173
})
101
174
```
102
175
103
-
You can unbind using `unbind`:
104
-
105
-
```javascript
106
-
client.unbind('connected', hello)
107
-
```
108
-
109
-
110
176
### Events on the StreamrClient instance
111
177
112
178
Name | Handler Arguments | Description
@@ -128,6 +194,6 @@ no_resend | | Fired after `resending` in case there was nothing to resend.
128
194
129
195
The Streamr JS client library supports [debug](https://github.com/visionmedia/debug) for logging.
130
196
131
-
In node.js, start your app like this: `DEBUG=StreamrClient node your-app.js`
197
+
In node.js, start your app like this: `DEBUG=StreamrClient* node your-app.js`
132
198
133
199
In the browser, include `debug.js` and set `localStorage.debug = 'StreamrClient'`
0 commit comments