@pryv/monitor

Monitor add-on for pryv

Extends the Pryv JavaScript library with event-driven notifications of changes on a Pryv.io account.

Usage

The add-on extends pryv with a pryv.Monitor class.

Importing

NPM

npm install --save pryv @pryv/monitor, then in your code (the add-on must be loaded once only):

const pryv = require('pryv');
require('@pryv/monitor')(pryv);

<script> tag

pryv-monitor.js must be loaded after pryv.js:

<script src="https://api.pryv.com/lib-js/pryv.js"></script>
<script src="https://api.pryv.com/lib-js/pryv-monitor.js"></script>

Other distributions available:

• ES6 version: https://api.pryv.com/lib-js-monitor/pryv-monitor-es6.js
• pryv library bundled with Socket.IO and Monitor add-ons: https://api.pryv.com/lib-js/pryv-socket.io-monitor.js.

Using pryv.Monitor

Once the add-on is loaded, pryv.Monitor can be instantiated.

Constructor

new pryv.Monitor({apiEndpoint | connection}, eventsGetScope)

• apiEndpoint: an API endpoint URL (see app guidelines)
• connection: a pryv.Connection instance (see library README)
• eventsGetScope: event.get parameters (see API reference)

Event listeners

Register event listeners for data changes on the specified scope. pryv.Monitor extends EventEmitter so you can register listeners with:

monitor.on(event, callback)

The possible events are:

• event: on Pryv event creation and update; callback argument: the Pryv event
• eventDeleted: on Pryv event deletion; callback argument: an object with the id of the deleted Pryv event (e.g. {id: "...."})
• streams: on any change (creation, update, deletion) in the Pryv stream structure; callback argument: a streams.get result object (e.g. {streams: ...})
• error: on error; callback argument: the error or error message
• ready: emitted when the monitor is ready (for internal and UpdateMethod usage – see below)
• stop: when the monitor stops

Start monitoring

await monitor.start()

The monitor will fetch the entire dataset in the specified scope then trigger the change events accordingly.

Trigger Pryv events update

await monitor.updateEvents()

This will push a request to update Pryv events into the task stack. It will be executed as soon as the monitor has finished possible pending tasks.

Trigger streams update

await monitor.updateStreams()

This will push a request to update Pryv streams into the task stack. It will be executed as soon as the monitor has finished possible pending tasks.

Add auto-update method

monitor.addUpdateMethod(updateMethod)

Update methods can be triggered automatically with:

• EventsTimer

  new pryv.Monitor.UpdateMethod.EventsTimer(ms)

  This will call monitor.updateEvents() every ms milliseconds (intended for demonstrative purposes).
• Socket

  new pryv.Monitor.UpdateMethod.Socket()

  This uses the Socket.IO add-on to relay notifications from Pryv.io to the monitor.
• Custom: You can design your own update method by extending the UpdateMethod class.

Stop monitoring

monitor.stop()

The monitor will stop auto updaters and will throw errors if updateEvents() or updateStreams() are called. It can be restarted.

Known limitation

If an event's update moves it out of the monitor's scope – for example the event's streamIds property is updated to a stream not covered by the scope – the Pryv.io API does not currently provide the necessary synchronization mechanism to detect such a change.

Examples

const apiEndpoint = 'https://[e-mail]';

// set monitor scope to the stream 'diary'
const eventsGetScope = {'streamIds': [diary]};

// refresh the monitor using the 'timer' method with a refresh rate of 1 second
const monitor = new pryv.Monitor(apiEndpoint || connection, eventsGetScope)
  .on('event', (event) => {}) // event created or updated
  .on('streams', (streams) => {}) // streams structure changed
  .on('eventDelete', (event) => {}) // event deleted
  .addUpdateMethod(new pryv.Monitor.UpdateMethod.EventsTimer(1000)); // set refresh timer

// start the monitor
(async () => {
  await monitor.start();
}())

You can also chain start():

(async () => { 
  const monitor = await (new pryv.Monitor(apiEndpoint || connection, eventsGetScope)
      .on('event', (event) => {}))
    .start();
})();

Auto-update with web sockets

Node.js

Install packages: npm install pryv @pryv/socket.io @pryv/monitor

const pryv = require('pryv');
require('@pryv/socket.io')(pryv);
require('@pryv/monitor')(pryv);

const apiEndpoint = 'https://[e-mail]';
(async () => { 
  const monitor = await (new pryv.Monitor(apiEndpoint || connection, eventsGetScope)
      .on('event', (event) => {}))
    .addUpdateMethod(new pryv.Monitor.UpdateMethod.Socket())
    .start();
})();

Browser

<script src="https://api.pryv.com/lib-js/pryv.js"></script>
<script src="https://api.pryv.com/lib-js-socket.io/pryv-socket.io.js"></script>
<script src="https://api.pryv.com/lib-js-monitor/pryv-monitor.js"></script>
<!--
The previous lines can be replaced by the bundled version of the library:
<script src="https://api.pryv.com/lib-js/pryv-socket.io-monitor.js"></script>
-->

<script>
const apiEndpoint = 'https://[e-mail]';
(async () => { 
  const monitor = await (new pryv.Monitor(apiEndpoint || connection, eventsGetScope)
      .on('event', (event) => {}))
    .addUpdateMethod(new pryv.Monitor.UpdateMethod.Socket())
    .start();
})();
</script>

Example web app

See here for a simple app that allows to sign in to a Pryv.io platform, register to monitor events changes and create notes. You can try it running there.

Contributing

See the Pryv JavaScript library README

License

BSD-3-Clause