@pryv/monitor 1.0.4 → 2.3.0

package/README.md

@@ -1,236 +1,212 @@
-# Monitor add-on for Pryv lib-js
+# Monitor add-on for `pryv`
 
-Extends Pryv's [lib-js](https://github.com/pryv/lib-js) with event driven notifications for changes on a Pryv.io account.
+Extends the [Pryv JavaScript library](https://github.com/pryv/lib-js) with event-driven notifications of changes on a Pryv.io account.
 
-## Setup
 
-This library extends `Pryv` with a `Pryv.Monitor` class.
-
-### Browser
-
-Note: `pryv-monitor.js` must be loaded **after** `pryv.js`
-
-```html
-<script src="https://api.pryv.com/lib-js/pryv.js"></script>
-<script src="https://api.pryv.com/lib-js-monitor/pryv-monitor.js"></script>
-```
+## Usage
 
-#### Others distributions for browsers:
+The add-on extends `pryv` with a `pryv.Monitor` class.
 
-- ES6: `https://api.pryv.com/lib-js-monitor/pryv-monitor-es6.js` 
-- Socket.io + Monitor + Lib-js: `https://api.pryv.com/lib-js/pryv-socket.io-monitor.js`. 
 
-### Node.js
+### Importing
 
-```bash
-npm install pryv @pryv/monitor
-```
+#### NPM
 
-In your project files, load it **once only**. The Pryv javascript package will be patched with monitor capabilities.
+`npm install --save pryv @pryv/monitor`, then in your code (the add-on must be loaded **once only**):
 
-```javascript
-const Pryv = require('pryv');
-require('@pryv/monitor')(Pryv);
+```js
+const pryv = require('pryv');
+require('@pryv/monitor')(pryv);
 ```
 
-## Usage
-
-Once Monitor has been set up, `Pryv.Monitor` can be instantiated.
+#### `<script>` tag
 
-### Constructor
+`pryv-monitor.js` must be loaded **after** `pryv.js`:
 
-```javascript
-new Pryv.Monitor({apiEndpoint | connection}, eventsGetScope)
+```html
+<script src="https://api.pryv.com/lib-js/pryv.js"></script>
+<script src="https://api.pryv.com/lib-js/pryv-monitor.js"></script>
 ```
 
-- apiEndpointUrl: [App guidelines - ApiEnpoint](https://api.pryv.com/guides/app-guidelines/#auto-configuration)
-
-  Pryv.Connection: [lib-js Connection](https://github.com/pryv/lib-js#obtaining-a-pryvconnection)
+Other distributions available:
 
-- eventsGetScope: [events.get parameters](https://api.pryv.com/reference/#get-events)
+- 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`.
 
-### Event listeners
 
-Register event listeners for data changes on the `eventsGetScope`.
+### Using `pryv.Monitor`
 
-**Monitor** extends [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
+Once the add-on is loaded, `pryv.Monitor` can be instantiated.
 
-You can register to them using: 
+#### Constructor
 
-```javascript
-monitor.on({event}, {callback})
+```js
+new pryv.Monitor({apiEndpoint | connection}, eventsGetScope)
 ```
 
-#### Events:
-
-- `event`: on every Pryv event **creation** and **update**
-
-callback argument: the Pryv event
+- `apiEndpoint`: an API endpoint URL (see [app guidelines](https://api.pryv.com/guides/app-guidelines/#auto-configuration))
+- `connection`: a `pryv.Connection` instance (see [library README](https://github.com/pryv/lib-js#obtaining-a-pryvconnection))
+- `eventsGetScope`: `event.get` parameters (see [API reference](https://api.pryv.com/reference/#get-events))
 
-- `eventDeleted`: on Pryv event deletion
+#### Event listeners
 
-callback argument: `{id: "...."}` the id of the deleted Pryv event
+Register event listeners for data changes on the specified scope. `pryv.Monitor` extends [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) so you can register listeners with:
 
-- `streams`: on any change (creation, update, deletion) in the Pryv stream structure
-
-callback argument: `{streams: ...}` as the [streams.get](https://api.pryv.com/reference/#get-streams) result
-
-- `error`: on error
-
-callback argument: The error or an error message
+```js
+monitor.on(event, callback)
+```
 
-- `ready`: Emitted when the monitor is ready (For internal and UpdateMethod usage)
+The possible events are:
 
-- `stop`: When the monitor stops
+- `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`](https://api.pryv.com/reference/#get-streams) 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
 
-```javascript
+```js
 await monitor.start()
 ```
 
-When starting, the monitor will fetch entire dataset covered by the `eventsGetScope` and trigger the changes event accordingly.
+The monitor will fetch the entire dataset in the specified scope then trigger the change events accordingly.
 
 #### Trigger Pryv events update
 
-```javascript
+```js
 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 eventual pending tasks.
+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
 
-```javascript
+```js
 await monitor.updateStreams()
 ```
 
-This will push a request to update Pryv streams into task the stack. It will be executed as soon as the monitor has finished eventual pending tasks.
+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
 
-```javascript
-monitor.addUpdateMethod({UpdateMethod})
+```js
+monitor.addUpdateMethod(updateMethod)
 ```
 
 Update methods can be triggered automatically with:
 
-- **EventsTimer** 
-
-```javascript
-new Pryv.Monitor.UpdateMethod.EventsTimer({ms})
-```
-
-This will call `monitor.updateEvents()` regularly at a rate `{ms}` in milliseconds (It has no real world but for demonstrative purposes).
-  
-- **Socket**
-
-```javascript
-new Pryv.Monitor.UpdateMethod.Socket()
-```
-  
-Based on websockets, it uses [lib-js-socket.io](https://github.com/pryv/lib-js-socket.io) to relay notification from Pryv.io to the monitor.
-  
-- **Custom**
+- `EventsTimer`
+  ```js
+  new pryv.Monitor.UpdateMethod.EventsTimer(ms)
+  ```
+  This will call `monitor.updateEvents()` every `ms` milliseconds (intended for demonstrative purposes).
+- `Socket`
+  ```js
+  new pryv.Monitor.UpdateMethod.Socket()
+  ```
+  This uses the [Socket.IO add-on](https://github.com/pryv/lib-js/tree/master/components/pryv-socket.io#readme) to relay notifications from Pryv.io to the monitor.
+- **Custom**: You can design your own update method by extending the [`UpdateMethod`](https://github.com/pryv/lib-js/tree/master/components/pryv-monitor/src/UpdateMethod/UpdateMethod.js) class.
 
-You can design your own UpdateMethod by extending the [UpdateMethod](https://github.com/pryv/lib-js-monitor/blob/master/src/UpdateMethod/UpdateMethod.js) class.
-  
 #### Stop monitoring
 
-```javascript
+```js
 monitor.stop()
 ```
 
-The monitor will stop auto updaters and will throw errors if `updateEvents` or `updateStreams` is called.
+The monitor will stop auto updaters and will throw errors if `updateEvents()` or `updateStreams()` are called.
+It can be restarted.
+
 
-A monitor can be restarted.
+### Known limitation
 
-## Example
+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.
 
 
-```javascript
+### Examples
+
+```js
 const apiEndpoint = 'https://ck6bwmcar00041ep87c8ujf90@drtom.pryv.me';
 
-// reduce the eventsGetScope of the monitor to the stream: diary
+// set monitor scope to the stream 'diary'
 const eventsGetScope = {'streamIds': [diary]};
 
-// refresh the monitor using the 'timer' method with a refreshrate of 5 seconds
-
-const monitor = new Pryv.Monitor(apiEndpoint || connection, eventsGetScope)
-	.on('event', (event) => {}) // per event - new or change
-	.on('streams', (streams) => {}) // all streams structure
-	.on('eventDelete', (event) => {}) // an event needs to be deleted
-	.addUpdateMethod(new Pryv.Monitor.UpdateMethod.EventsTimer(1000)); // add refresh timer
+// 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(); // start the monitor
+  await monitor.start();
 }())
 ```
 
-Chain (async) `.start()`
+You can also chain `start()`:
 
-```javascript
+```js
 (async () => { 
-	const monitor = await (new Pryv.Monitor(apiEndpoint || connection, eventsGetScope)
-		.on('event', (event) => {})))
-		.start();
+  const monitor = await (new pryv.Monitor(apiEndpoint || connection, eventsGetScope)
+      .on('event', (event) => {}))
+    .start();
 })();
 ```
 
-### Auto-update with web sockets
+#### Auto-update with web sockets
 
-#### Node.js
+##### Node.js
 
-```javascript
-const Pryv = require('pryv');
-require('@pryv/socket.io')(Pryv);
-require('../src/')(Pryv);
+Install packages: `npm install pryv @pryv/socket.io @pryv/monitor`
+
+```js
+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();
+  const monitor = await (new pryv.Monitor(apiEndpoint || connection, eventsGetScope)
+      .on('event', (event) => {}))
+    .addUpdateMethod(new pryv.Monitor.UpdateMethod.Socket())
+    .start();
 })();
 ```
 
-#### Browser
+##### Browser
 
 ```html
 <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();
+  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](`../../examples/monitor.html`) 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](https://api.pryv.com/lib-js/examples/monitor.html).
 
-### Example web app
-
-![Screenshot](examples/screenshot.png)
-
-The `./examples/index.html` file is a simple demo app that allows loging in a Pryv.io platform, register to events changes and create notes. 
-
-It can be tested on [http://pryv.github.io/lib-js-monitor](http://pryv.github.io/lib-js-monitor) 
 
-## Contribute
+## Contributing
 
-*Prerequisites*: Node 12
+See the [Pryv JavaScript library README](https://github.com/pryv/lib-js#contributing)
 
-- Setup: `npm run setup`
-- Build pryv-monitor.js library for browsers: `npm run build`, the result is published in `./dist`
-- Node Tests: `npm run test`
 
-## Known limitations
+## License
 
-- If an event's update makes it "out of eventsGetScope". For example an (in eventsGetScope) event streamIds[] property is "moved" to a streamId not convered by the eventsGetScope, the current Pryv.io API does not provide the necessary synchronization mechanism to detect such changes.
+[BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)

package/package.json

@@ -1,20 +1,7 @@
 {
   "name": "@pryv/monitor",
-  "version": "1.0.4",
-  "description": "Extends `pryv` lib-js with event driven notifications for changes on a Pryv.io account.",
-  "main": "src/index.js",
-  "scripts": {
-    "test": "mocha --reporter spec  test/*.test.js",
-    "setup": "./scripts/setup-environment-dev.sh",
-    "build": "webpack"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/pryv/lib-js-monitor"
-  },
-  "bugs": {
-    "url": "https://github.com/pryv/lib-js-monitor/issues"
-  },
+  "version": "2.3.0",
+  "description": "Extends `pryv` with event-driven notifications for changes on a Pryv.io account",
   "keywords": [
     "Pryv",
     "Pryv.io",
@@ -22,13 +9,15 @@
     "Scope",
     "Monitor"
   ],
-  "author": "Pryv S.A.",
+  "homepage": "https://github.com/pryv/lib-js/tree/master/components/pryv-monitor#readme",
+  "bugs": {
+    "url": "https://github.com/pryv/lib-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/pryv/lib-js"
+  },
   "license": "BSD-3-Clause",
-  "devDependencies": {
-    "@pryv/lib-js-common": "git+https://github.com/pryv/lib-js-common.git#1.0.3",
-    "@pryv/socket.io": "^1.0.2",
-    "chai": "^4.2.0",
-    "mocha": "^8.2.1",
-    "pryv": "^2.1.2"
-  }
+  "author": "Pryv S.A. <info@pryv.com> (https://pryv.com)",
+  "main": "src/index.js"
 }

package/src/Monitor.js

@@ -1,3 +1,7 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 const EventEmitter = require('events');
 const UpdateMethod = require('./UpdateMethod/');
 const _updateEvents = require('./lib/updateEvents');
@@ -5,37 +9,37 @@ const _updateStreams = require('./lib/updateStreams');
 const Changes = require('./lib/Changes');
 
 /**
- * @memberof Pryv
+ * @memberof pryv
  */
 class Monitor extends EventEmitter {
   /**
-   * 
-   * @param {(Pryv.PryvApiEndpoint|Pryv.Connection)} apiEndpointOrConnection ApiEnpoint or connection to use. 
-   * @param {Pryv.Monitor.Scope} [eventsGetScope={}] The Scope to monitor
+   *
+   * @param {(pryv.APIEndpoint|pryv.Connection)} apiEndpointOrConnection APIEndoint or connection to use
+   * @param {pryv.Monitor.Scope} [eventsGetScope={}] The Scope to monitor
    */
-  constructor(apiEndpointOrConnection, eventsGetScope = {}) {
+  constructor (apiEndpointOrConnection, eventsGetScope = {}) {
     super();
-    if (!Monitor.Pryv) {
+    if (!Monitor.pryv) {
       throw new Error('package \'@pryv/monitor\' must loaded after package \'pryv\'');
     }
 
     this.eventsGetScope = { // default eventsGetScope values
-      fromTime: - Number.MAX_VALUE,
+      fromTime: -Number.MAX_VALUE,
       toTime: Number.MAX_VALUE,
-      modifiedSince: - Number.MAX_VALUE
-    }
+      modifiedSince: -Number.MAX_VALUE
+    };
     Object.assign(this.eventsGetScope, eventsGetScope);
 
-    if (apiEndpointOrConnection instanceof Monitor.Pryv.Connection) {
+    if (apiEndpointOrConnection instanceof Monitor.pryv.Connection) {
       this.connection = apiEndpointOrConnection;
     } else {
-      this.connection = new Monitor.Pryv.Connection(apiEndpointOrConnection);
+      this.connection = new Monitor.pryv.Connection(apiEndpointOrConnection);
     }
     this.states = {
       started: false,
       starting: false, // in phase of initializing
       updatingEvents: false, // semaphore to prevent updating events in parallel
-      updatingStreams: false, // semaphore to prevent updating streams in parallel
+      updatingStreams: false // semaphore to prevent updating streams in parallel
     };
   }
 
@@ -43,7 +47,7 @@ class Monitor extends EventEmitter {
    * Start the monitor
    * @returns {Monitor} this
    */
-  async start() {
+  async start () {
     if (this.states.started || this.states.starting) return this;
     this.states.starting = true;
     await _updateStreams(this);
@@ -62,7 +66,7 @@ class Monitor extends EventEmitter {
    * request and update of events
    * @returns {Monitor} this
    */
-  async updateEvents() {
+  async updateEvents () {
     if (!this.states.started) {
       throw new Error('Start Monitor before calling update Events');
     }
@@ -94,7 +98,7 @@ class Monitor extends EventEmitter {
    * request and update of streams
    * @returns {Monitor} this
    */
-  async updateStreams() {
+  async updateStreams () {
     if (!this.states.started) {
       throw new Error('Start Monitor before calling update Streams');
     }
@@ -125,20 +129,19 @@ class Monitor extends EventEmitter {
   /**
    * @private
    * Called after init phase and each updateEvents
-   * Advertise the update method or any listener that the Monitor is ready 
+   * Advertise the update method or any listener that the Monitor is ready
    * for a next event update
    */
-  ready() {
-    if (!this.states.started) return; // it might be stoped 
+  ready () {
+    if (!this.states.started) return; // it might be stoped
     this.emit(Changes.READY);
   }
 
-
   /**
    * Stop monitoring (no event will be fired anymore)
    * @returns {Monitor} this
    */
-  stop() {
+  stop () {
     if (!this.states.started) return this;
     if (this.states.starting) throw new Error('Process is starting, wait for the end of initialization to stop it');
     this.emit(Changes.STOP);
@@ -150,14 +153,14 @@ class Monitor extends EventEmitter {
    * Used by updateMethods to be sure they can call updateXXX methods
    * @property {Boolean} started - true is monitor is started
    */
-  get started() {
+  get started () {
     return this.states.started;
   }
 
   /**
    * Initialize the updateMethods with this Monitor
    * @callback Monitor~UpdateMethod
-   * @param {Monitor} setMonitor 
+   * @param {Monitor} setMonitor
    */
 
   /**
@@ -167,14 +170,11 @@ class Monitor extends EventEmitter {
    * @param {Monitor~UpdateMethod} updateMethod - the auto-update method
    * @returns {Monitor} this
    */
-  addUpdateMethod(updateMethod) {
-    if (false) {
-      throw new Error('Argument is not a valid UpdateMethod instance');
-    }
+  addUpdateMethod (updateMethod) {
     updateMethod.setMonitor(this);
-    return this
+    return this;
   }
 }
 
 Monitor.UpdateMethod = UpdateMethod;
-module.exports = Monitor;
+module.exports = Monitor;

package/src/UpdateMethod/EventsTimer.js

@@ -1,10 +1,14 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 const UpdateMethod = require('./UpdateMethod');
 
 class EventsTimer extends UpdateMethod {
   /**
    * @param {Number} updateRateMS - the refresh rate in milliseconds
    */
-  constructor(updateRateMS) {
+  constructor (updateRateMS) {
     super();
     this.timer = null;
     if (!updateRateMS || isNaN(updateRateMS) || updateRateMS < 1) {
@@ -15,10 +19,10 @@ class EventsTimer extends UpdateMethod {
 
   async ready () {
     if (this.timer != null) clearTimeout(this.timer);
-    this.timer = setTimeout(() => { 
-      if (this.monitor.started) this.monitor.updateEvents() 
+    this.timer = setTimeout(() => {
+      if (this.monitor.started) this.monitor.updateEvents();
     }, this.updateRateMS);
   }
 }
 
-module.exports = EventsTimer;
+module.exports = EventsTimer;

package/src/UpdateMethod/Socket.js

@@ -1,22 +1,23 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 
 const UpdateMethod = require('./UpdateMethod');
 const Changes = require('../lib/Changes');
 
 class Socket extends UpdateMethod {
-  constructor() {
-    super();
-  }
-
-  async ready() {
+  async ready () {
     if (this.socket) return;
     if (!this.monitor.connection.socket) {
       throw new Error('You should load package @pryv/socket.io to use monitor with websockets');
     }
     this.socket = await this.monitor.connection.socket.open();
-    this.socket.on('eventsChanged', () => {  this.monitor.updateEvents(); });
+    this.socket.on('eventsChanged', () => { this.monitor.updateEvents(); });
     this.socket.on('streamsChanged', () => { this.monitor.updateStreams(); });
-    this.socket.on('error', (error) => { this.monitor.emit(Changes.ERROR.error); }); 
-  };
+    /* eslint-disable-next-line node/handle-callback-err */
+    this.socket.on('error', (error) => { this.monitor.emit(Changes.ERROR.error); });
+  }
 
   async stop () {
     if (!this.socket) return;
@@ -24,4 +25,4 @@ class Socket extends UpdateMethod {
     this.socket = null;
   }
 }
-module.exports = Socket;
+module.exports = Socket;

package/src/UpdateMethod/UpdateMethod.js

@@ -1,16 +1,20 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 const Changes = require('../lib/Changes');
 /**
  * Interface for UpdateMonitor
- * @memberof Pryv.Monitor
+ * @memberof pryv.Monitor
  * @constructor {Monitor~UpdateMethod} updateMethod.setMonitor - set only once
  */
 class UpdateMethod {
   /**
-   * Assign a Monitor to this updater. 
+   * Assign a Monitor to this updater.
    * Usually called by the monitor itself on monitor.addUpdateMethod()
-   * @param {Monitor} monitor 
+   * @param {Monitor} monitor
    */
-  setMonitor(monitor) { 
+  setMonitor (monitor) {
     if (this.monitor) {
       throw new Error('An update Method can be assigned to one monitor only');
     }
@@ -27,13 +31,13 @@ class UpdateMethod {
    * Called with no params, when all update tasks are done.
    * Also used at "start" call
    */
-  async ready() { }
+  async ready () { }
 
   /**
    * Should be overwritten by subclases
    * Called with no params, when monitor is stoped: updater should be stoped too.
    */
-  async stop() { }
+  async stop () { }
 }
 
-module.exports = UpdateMethod;
+module.exports = UpdateMethod;

package/src/UpdateMethod/index.js

@@ -1,7 +1,10 @@
-
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 
 module.exports = {
   Null: require('./UpdateMethod'),
   Socket: require('./Socket'),
   EventsTimer: require('./EventsTimer')
-}
+};