@pryv/monitor
v2.3.8
Published
Extends `pryv` with event-driven notifications for changes on a Pryv.io account
Downloads
28
Readme
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
: apryv.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 eventeventDeleted
: on Pryv event deletion; callback argument: an object with theid
of the deleted Pryv event (e.g.{id: "...."}
)streams
: on any change (creation, update, deletion) in the Pryv stream structure; callback argument: astreams.get
result object (e.g.{streams: ...}
)error
: on error; callback argument: the error or error messageready
: emitted when the monitor is ready (for internal andUpdateMethod
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
This will callnew pryv.Monitor.UpdateMethod.EventsTimer(ms)
monitor.updateEvents()
everyms
milliseconds (intended for demonstrative purposes).Socket
This uses the Socket.IO add-on to relay notifications from Pryv.io to the monitor.new pryv.Monitor.UpdateMethod.Socket()
- 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://[email protected]';
// 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://[email protected]';
(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://[email protected]';
(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