resgateio / resclient

Javascript client implementing the RES-Client Protocol.

ResClient for Javascript
Synchronize Your Clients

---

Javascript client library implementing the RES-Client Protocol. Used to establish WebSocket connections to Resgate, to get your data synchronized in real-time.

Visit Resgate.io for more information.

Installation

With npm:

npm install resclient

With yarn:

yarn add resclient

Example usage

import ResClient from 'resclient';

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

client.get('example.mymodel').then(model => {
    console.log(model.message);

    let onChange = () => {
        console.log("New message: " + model.message);
    };

    // Listen to changes for 5 seconds, eventually unsubscribing
    model.on('change', onChange);
    setTimeout(() => {
        model.off('change', onChange);
    }, 5000);
});

Full examples

Example	Description
React	React client implementation of the Book Collection example.
Vue.js	Vue.js client implementation of the Book Collection example.
Vue 3	Vue 3 client implementation of the Book Collection example.
Modapp	Book Collection example from Resgate repository

Note

All examples are complete with both service and client.

Usage in Node.js

To connect with WebSockets in Node.js, we must use a library implementing the WebSocket API, such as isomorphic-ws.

var WebSocket = require('isomorphic-ws');
var ResClient = require('resclient').default;
// Create instance with a WebSocket factory function
var client = new ResClient(() => new WebSocket("ws://localhost:8080"));

Documentation

Markdown documentation

resclient's Issues

Data value

Issue

Add support for RES Protocol's data value.

Notes

• Deep equality test should be used when re-synchronizing values.

Update dependencies

Issue

Dependencies and dev dependencies should be updated.

Solution

Run:

npm update

And update any deprecated configuration.

No ResClient instance events

Issue

ResClient instance event handler is not called after using ResClient.on() for events such as connect, disconnect, and error.

Solution

Fix the bug causing the event handler not to register properly.

Update documentation to properly show which events are available.

Continuous integration

Issue

Travis CI and Coveralls should be added to the repository to provide continuous integration tests.

Props on ResModel

Issue

ResModel will currently discard properties where the name matches any of its prototype methods: on, off, call, etc.

In case a model has any of those properties, they will not be available on the client.

Solution

Add a props getter method to ResModel, which returns an anonymous object with all model properties. This can be used to access otherwise overridden properties:

Example:

model.on('change', handler); // Add listener with the on method
model.props.on; // Access the property named "on"

Notes

Any non-conflicting properties should still be available without having to use the props getter.

Dependency on document

Issue

In ResClient.js there is a dependency on document:

_resolvePath(url) {
	if (url.match(/^wss?:\/\//)) {
		return url;
	}

	let a = document.createElement('a');
	a.href = url;

	return a.href.replace(/^http/, 'ws');
}

This makes ResClient unusable in node.js environments.

Solution

Remove the document dependency and replace it with a more general solution.

Soft reference support

Issue

Support for soft references should be implemented.

Protocol v1.2.0 support

Issue

RES Client protocol v1.2.0 support should be added.

Scope

• Add support for resource response on call request
• Deprecate new request (create)

Move repository to resgateio organization

Issue

The resclient respository is currently hosted under jirenius. But with the launch of resgate.io and the stable release, it should be moved to the resgateio organisation.

Configurable delay durations

Issue

It should be possible to configure the duration for delays:

• reconnectDelay - Milliseconds between WebSocket reconnect attempts. Defaults to 3000.
• subscribeStaleDelay - Milliseconds until a subscribe attempt is made on a stale resource. Zero means no attempt to subscribe. Defaults to 2000.
• subscribeRetryDelay - Milliseconds between subscribe attempts on a stale resource after a failed stale subscribe. Zero means no retries. Defaults to 10000.
• unsubscribeDelay - Milliseconds between stopping listening to a resource, and the resource being unsubscribed. Defaults to 5000.

Unsubscribe count field

Issue

Add support for RES Client Protocol's unsubscribe count field.

Notes

• When connecting an older Resgate supporting RES Protocol <= v1.2.0, the client should use legacy behavior.

Add getClient to ResModel and ResCollection

Issue

When given a ResModel or ResCollection instance, there is currently no way to access the associated ResClient instance except by accessing the "private" _api property.

Solution

Add a getClient() method to ResModel and ResCollection that returns the ResClient instance.

Static resource type

Issue

Add support for RES Protocol's static resource type.

Notes

• A static resource should result in a ResStatic class instance.
• The ResStatic class should have a data getter property.

Add examples

Issue

There is a need for examples showing how ResClient may be used with different frameworks such as Modapp, React, Vue.js, and Angular.

Solution

Create an examples folder, similar to the one in the resgate respository, but with examples aimed for ResClient usage. These examples should contain both a working service as well as a client.

Example for Modapp will be skipped for now, as the resgate respository already has examples such as book-collection which uses Modapp.

Generate typescript types on build

Issue

Typescript types should be generated on build.

Missing docs? Example of setting model values using ResClient/ResModel?

Hey all!

First, thanks so much for this project. It's been a great journey so far and I am still learning.

I'm trying to understand how to use ResClient/ResModel to set model properties (including nested properties/arrays/etc), but am having trouble finding the documentation for this.

At first glance it seems like this is a gap in the documentation, which is why I am filing an issue, not asking a question on the forums (though I will also do that.) Could someone point me in the right direction if I have missed them? Otherwise, please consider this a polite note that there may be a gap :)

Thanks so much!

Model property deletion on reset

Issue

When a model is resynchronized, and the new version of the model is missing properties that existed in the cached version, those properties are not deleted as expected.

Resource not found in cache

Issue

ResClient may, in case of high activity, give the error:

Resource not found in cache.

Even when the resource should have been available in the cache.

How to reproduce

Not yet known.

Resgate disconnect tests

Issue

Unit tests should be added to cover ResClient's behavior on unexpected disconnects.

Scope

The tests should describe unexpected disconnect, and test that:

• it does nothing if no subscriptions exists and no requests are pending
• it connects after an unexpected disconnect on first subscription
• it connects after an unexpected disconnect on first call
• it directly attempts to reconnect and resubscribe to existing subscriptions
• it rejects pending requests with a system.connectionError error

Support NodeJS

Issue

It should be possible to use ResClient in non-browser environments such as NodeJS.

It is currently not possible as ResClient depends on the browser native WebSocket object.

Solution

ResClient could take a WebSocket factory callback function as an alternative to the url parameter. The factory function would then be used instead of creating a native WebSocket object.

Example:

const ResClient = require('resclient').default;
 // This package should provide a similar API as the browser native WebSocket.
const WebSocket = require('isomorphic-ws');

let client = new ResClient(() => new WebSocket('ws://localhost:8080', {
  origin: 'http://localhost:8080'
}));

ResClient would test the first constructor parameter to see if typeof(urlOfFactory) == 'function', in which case the function would be used instead of calling new WebSocket.

Notes

The documentation would specify the expected behavior of the returned WebSocket object in a jsdoc3 interface. The interface should only contain the features of WebSocket used by ResClient.

Resource responses not unsubscribing on no listeners

Issue

When receiving a resource response from a call request, the resource received is not unsubscribed after the unsubscribeDelay duration has passed, even if no listener has been added to the resource.

Example for Vue 3

Issue

Because of the way Vue 3 uses Proxy to get reactivity, the existing Vue.js example does not work properly when converted to Vue 3.

gmae crashe every time tryto join

Define underscore properties as non-enumerable

As it sits currently, models can be very hard to read when logged due to the numerous underscored properties (which I assume to be private, "don't use this" properties). These properties are shown when logging to the console, and you have to go out of your way to hide them, or sift through them for the actual data on the model. This can be combatted with simple defineProperty/defineProperties call

const obj = {};
Object.defineProperty(obj, "hidden1", { value: "whatever", enumerable: false });
Object.defineProperty(obj, "_hidden2", { value: "hi", enumerable: false });
Object.defineProperties(obj, {
    hidden3: {
        value: "this is easy",
        enumerable: false
    },
    _hidden4: {
        value: "please my adhd is killing me",
        enumerable: false
    }
});

console.log(obj);
console.log(obj.hidden1);
console.log(obj._hidden2);
console.log(obj.hidden3);
console.log(obj._hidden4);

The first log shows no properties, but the next 4 clearly show them as still accessible and usable.

Bad ResCollection declaration generated

Issue

The Typescript generates a poor declaration for the ResCollection.