@pryv/monitor

    2.3.6 • Public • Published

    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)

    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://ck6bwmcar00041ep87c8ujf90@drtom.pryv.me';
    
    // 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://ck60yn9yv00011hd3vu1ocpi7@jslibtest.pryv.me';
    (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://ck60yn9yv00011hd3vu1ocpi7@jslibtest.pryv.me';
    (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

    Install

    npm i @pryv/monitor

    DownloadsWeekly Downloads

    67

    Version

    2.3.6

    License

    BSD-3-Clause

    Unpacked Size

    27.4 kB

    Total Files

    16

    Last publish

    Collaborators

    • perki
    • kebetsi
    • sgoumaz