Getting started with deepstreamHub is easy and takes less than ten minutes. However, if you have any questions, please get in touch.
This guide will show you how to build backend processes in NodeJS using deepstreamHub's three core concepts: Records, Events and RPCs.
Create a free account and get your API key
Connect to deepstreamHub and log in
Install the deepstream client SDK using npm
npm install deepstream.io-client-js --save
... or yarn
yarn add deepstream.io-client-js
Import it into your app
const deepstream = require( 'deepstream.io-client-js' );
Get your app url from the dashboard and establish a connection to deepstreamHub
const ds = deepstream( '<YOUR APP URL>' );
and log in (we didn't configure any authentication, so there are no credentials required)
ds.login();
Records (realtime datastore)
Records are the documents in deepstreamHub’s realtime datastore. A record is identified by a unique id and can contain any kind of JSON data. Clients and backend processes can create, read, write, update and observe the entire record as well as paths within it. Any change is immediately synchronized amongst all connected subscribers.
Records can be arranged in lists and collections and can contain references to other records to allow for the modelling of relational data structures.
You can learn more about records in the records tutorial.
Creating a new record or retrieving an existent one is done using getRecord()
var myRecord = ds.record.getRecord( 'test/johndoe' );
Values can be stored using the .set() method
// you can set the entire data
myRecord.set({
firstname: 'John',
lastname: 'Doe'
});
// or just a path
myRecord.set( 'hobbies', [ 'sailing', 'reading' ] );
and retrieved using .get()
myRecord.get(); // returns the entire data
myRecord.get( 'hobbies[1]' );// returns 'reading'
subscribe to changes made by you or other clients using .subscribe()
myRecord.subscribe( data => {}); // get notified when any data changes
myRecord.subscribe( 'firstname', firstname => {});// get notified when first name changes
you can remove subscriptions with .unsubscribe(), tell the server you're no longer interested in the record using .discard() or delete it using .delete().
Events (publish-subscribe)
Events are deepstreamHub’s publish-subscribe mechanism. Clients and backend processes can subscribe to event-names (sometimes also called “topics” or “channels”) and receive messages published by other endpoints.
Events are non-persistent, one-off messages. For persistent data, please use records.
Clients and backend processes can receive events using .subscribe()
ds.event.subscribe( 'test-event', function( eventData ){ /*do stuff*/ });
... and publish events using .emit()
ds.event.emit( 'test-event', {some: 'data'} );
RPCs (request-response)
Remote Procedure Calls are deepstreamHub’s request-response mechanism. Clients and backend processes can register as “providers” for a given RPC, identified by a unique name. Other endpoints can request said RPC.
deepstreamHub will route requests to the right provider, load-balance between multiple providers for the same RPC, and handle data-serialisation and transport.
.make()
ds.rpc.make( 'multiply-numbers', { a: 6, b: 7 }, function( err, result ){
//result === 42
});
and answer it using .provide()
ds.rpc.provide( 'multiply-numbers', function( data, response ){
resp.send( data.a * data.b );
});
What’s next?
Head over to the example app section to try some more concrete usecases.