streamr-client v8.5.5

Streamr JavaScript Client

By using this client, you can easily interact with the Streamr API from JavaScript-based environments, such as browsers and node.js. You can, for example, subscribe to real-time data in Streams, produce new data to Streams, and create new Streams.

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.

The client uses websockets for producing and consuming messages to/from streams. It should work in all modern browsers.

Installation

The client is available on npm and can be installed simpy by:

npm install streamr-client

Usage

Here are some quick examples. More detailed examples for the browser and node.js can be found here.

Creating a StreamrClient instance

const client = new StreamrClient({
    // See below for more options
    auth: {
        apiKey: 'your-api-key'
    }
})

Subscribing to real-time events in a stream

const sub = client.subscribe(
    {
        stream: 'streamId',
        apiKey: 'secret',       // Optional. If not given, uses the apiKey given at client creation time.
        partition: 0,           // Optional, defaults to zero. Use for partitioned streams to select partition.
        // optional resend options here
    },
    (message, metadata) => {
        // This is the message handler which gets called for every incoming message in the Stream.
        // Do something with the message here!
    }
)

Programmatically creating a Stream

client.getOrCreateStream({
    name: 'My awesome Stream created via the API',
})
    .then((stream) => {
        console.log(`Stream ${stream.id} has been created!`)
        // Do something with the Stream, for example call stream.publish(message)
    })

Producing data points to a Stream

// Here's our example data point
const msg = {
    temperature: 25.4,
    humidity: 10,
    happy: true
}

// Publish using the Stream id only
client.publish('my-stream-id', msg)

// Or alternatively, via the Stream object (from e.g. getOrCreateStream)
stream.publish(msg)

Client options

Authentication options

Message handler callback

The second argument to client.subscribe(options, callback) is the callback function that will be called for each message as they arrive. Its arguments are as follows:

StreamrClient object

Connecting

Managing subscriptions

Stream API

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.

Listening to state changes of the client

on(eventName, function) | Binds a function to an event called eventName once(eventName, function) | Binds a function to an event called eventName. It gets called once and then removed. removeListener(eventName, function) | Unbinds the function from events called eventName

Stream object

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.

Subscription options

Note that only one of the resend options can be used for a particular subscription. The default functionality is to resend nothing, only subscribe to messages from the subscription moment onwards.

// Resend N most recent messages
resend: {
    last: 10,
}

// Resend from a specific message reference up to the newest message
resend: {
    from: {
        timestamp: 12345,
        sequenceNumber: 0, // optional
    }
    publisher: 'publisherId', // optional
    msgChainId: 'msgChainId', // optional
}

// Resend a limited range of messages
resend: {
    from: {
        timestamp: 12345,
        sequenceNumber: 0, // optional
    },
    to: {
        timestamp: 54321,
        sequenceNumber: 0, // optional
    },
    publisher: 'publisherId', // optional
    msgChainId: 'msgChainId', // optional
}

Binding to events

The client and the subscriptions can fire events as detailed below. You can bind to them using on:

    // The StreamrClient emits various events
	client.on('connected', () => {
	    console.log('Yeah, we are connected now!')
	})

    // So does the Subscription object
	const sub = client.subscribe(...)
	sub.on('subscribed', () => {
	    console.log(`Subscribed to ${sub.streamId}`)
	})

Events on the StreamrClient instance

Events on the Subscription object

Logging

The Streamr JS client library supports debug for logging.

In node.js, start your app like this: DEBUG=StreamrClient* node your-app.js

In the browser, include debug.js and set localStorage.debug = 'StreamrClient'