ResClient

How to connect to Resgate to access realtime updates using ResClient.

All resources and methods can be accessed using ordinary HTTP requests. But to get realtime updates from Resgate, you should be using ResClient instead.

What is ResClient?

ResClient¹ is a javascript client library that uses WebSocket and the RES-client protocol² to communicate with Resgate.

It can be installed with npm:

npm install resclient --save

Or with yarn:

yarn add resclient

Or by downloading it from a CDN:

<script src="https://cdn.jsdelivr.net/npm/resclient@latest/dist/resclient.min.js"></script>

Basic usage

Connect

ResClient need no prior knowledge about the API it connects to. All you need to do is provide the WebSocket URL to Resgate:

let client = new ResClient('ws://localhost:8080');

Tip

When running any of the examples, you can open your browser’s developer tools console to try out running a few commands manually.
client.getHostUrl();
All examples stores the client instance in the global variable: client

Get resource

And then get a promise to the resource you want, such as the example.model from Chapter 1 - Hello World, like this:

client.get('example.model').then(model => {
	console.log(model.message)
}).catch(err => {
	console.error(err);
});

Model properties

Models fetched using ResClient are objects whose properties reflect those of the backend resource. Therefore you can access the values directly, like this:

console.log(model.myvalue);

Collection items

Collections are also objects, but they implement the iterable interface. This means that, while they are not arrays, you can still iterate over them to get the items:

// for .. of iteration
for (let item of collection) { /* ... */ }
// map using toArray
collection.toArray().map(item => { /* ... */ });

Warning

ResClient’s models and collections should never be mutated directly.
Updates to the resources should strictly be done by ResClient itself, based on events sent from Resgate.

Listen to events

When a resource is fetched, ResClient will automatically start subscribing to events on that resource.

Add a callback using the on method to act on incoming events, like this:

let onChange = function(changed) {
	console.log("Model was updated");
};

client.get('example.model').then(model => {
	model.on('change', onChange);
});

client.get('example.collection').then(collection => {
	collection.on('add', onAdd);
	collection.on('remove', onRemove);
});

To stop listening for events, call the off method with the same parameters, like this:

model.off('change', onChange);

Note

ResClient will eventually unsubscribe to a resource when it no longer has any registered callbacks.

Therefore, don’t keep a resource object without registering any callback, as the resource might be unsubscribed and discarded by the time you wish to use it.

To prevent a resource from being unsubscribed, you may also call on without arguments:
// Increase reference count to prevent unsubscription
model.on()

// Decrease reference count to allow unsubscription
model.off()