@pryv/monitor 2.4.6 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pryv/monitor",
-  "version": "2.4.6",
+  "version": "3.0.0",
   "description": "Extends `pryv` with event-driven notifications for changes on a Pryv.io account",
   "keywords": [
     "Pryv",
@@ -15,10 +15,13 @@
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/pryv/lib-js"
+    "url": "git://github.com/pryv/lib-js.git"
   },
   "license": "BSD-3-Clause",
   "author": "Pryv S.A. <info@pryv.com> (https://pryv.com)",
   "main": "src/index.js",
-  "types": "src/index.d.ts"
+  "types": "src/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  }
 }

package/src/Monitor.js

@@ -9,16 +9,20 @@ const _updateStreams = require('./lib/updateStreams');
 const Changes = require('./lib/Changes');
 
 /**
+ * Monitor changes on a Pryv.io account.
+ * Emits events when data changes are detected.
  * @memberof pryv
+ * @extends EventEmitter
  */
 class Monitor extends EventEmitter {
   /**
-   *
-   * @param {(pryv.APIEndpoint|pryv.Connection)} apiEndpointOrConnection APIEndoint or connection to use
-   * @param {pryv.Monitor.Scope} [eventsGetScope={}] The Scope to monitor
+   * Create a new Monitor
+   * @param {(string|Connection)} apiEndpointOrConnection - API endpoint URL or Connection instance
+   * @param {MonitorScope} [eventsGetScope={}] - The scope to monitor (events.get parameters)
    */
   constructor (apiEndpointOrConnection, eventsGetScope = {}) {
     super();
+    // @ts-ignore - pryv is set at runtime by extendPryvMonitor
     if (!Monitor.pryv) {
       throw new Error('package \'@pryv/monitor\' must loaded after package \'pryv\'');
     }
@@ -30,9 +34,11 @@ class Monitor extends EventEmitter {
     };
     Object.assign(this.eventsGetScope, eventsGetScope);
 
+    // @ts-ignore - pryv is set at runtime
     if (apiEndpointOrConnection instanceof Monitor.pryv.Connection) {
       this.connection = apiEndpointOrConnection;
     } else {
+      // @ts-ignore - pryv is set at runtime
       this.connection = new Monitor.pryv.Connection(apiEndpointOrConnection);
     }
     this.states = {
@@ -44,8 +50,8 @@ class Monitor extends EventEmitter {
   }
 
   /**
-   * Start the monitor
-   * @returns {Monitor} this
+   * Start the monitor and perform initial sync
+   * @returns {Promise<Monitor>} Promise resolving to this Monitor instance
    */
   async start () {
     if (this.states.started || this.states.starting) return this;
@@ -63,8 +69,8 @@ class Monitor extends EventEmitter {
   }
 
   /**
-   * request and update of events
-   * @returns {Monitor} this
+   * Request an events update according to the current scope
+   * @returns {Promise<Monitor>} Promise resolving to this Monitor instance
    */
   async updateEvents () {
     if (!this.states.started) {
@@ -95,8 +101,8 @@ class Monitor extends EventEmitter {
   }
 
   /**
-   * request and update of streams
-   * @returns {Monitor} this
+   * Request a streams update
+   * @returns {Promise<Monitor>} Promise resolving to this Monitor instance
    */
   async updateStreams () {
     if (!this.states.started) {
@@ -157,17 +163,11 @@ class Monitor extends EventEmitter {
     return this.states.started;
   }
 
-  /**
-   * Initialize the updateMethods with this Monitor
-   * @callback Monitor~UpdateMethod
-   * @param {Monitor} setMonitor
-   */
-
   /**
    * @private
-   * Called my UpdateMethod to share cross references
+   * Called by UpdateMethod to share cross references
    * Set a custom update method
-   * @param {Monitor~UpdateMethod} updateMethod - the auto-update method
+   * @param {Object} updateMethod - the auto-update method
    * @returns {Monitor} this
    */
   addUpdateMethod (updateMethod) {

package/src/UpdateMethod/EventsTimer.js

@@ -4,9 +4,14 @@
  */
 const UpdateMethod = require('./UpdateMethod');
 
+/**
+ * Update method that polls for event changes at a fixed interval.
+ * @memberof pryv.Monitor
+ * @extends UpdateMethod
+ */
 class EventsTimer extends UpdateMethod {
   /**
-   * @param {Number} updateRateMS - the refresh rate in milliseconds
+   * @param {number} updateRateMS - The refresh rate in milliseconds (must be > 1)
    */
   constructor (updateRateMS) {
     super();

package/src/UpdateMethod/Socket.js

@@ -6,17 +6,24 @@
 const UpdateMethod = require('./UpdateMethod');
 const Changes = require('../lib/Changes');
 
+/**
+ * Update method that uses @pryv/socket.io events for real-time updates.
+ * Requires @pryv/socket.io to be loaded.
+ * @memberof pryv.Monitor
+ * @extends UpdateMethod
+ */
 class Socket extends UpdateMethod {
   async ready () {
     if (this.socket) return;
+    // @ts-ignore - socket is added by @pryv/socket.io extension
     if (!this.monitor.connection.socket) {
       throw new Error('You should load package @pryv/socket.io to use monitor with websockets');
     }
+    // @ts-ignore - socket is added by @pryv/socket.io extension
     this.socket = await this.monitor.connection.socket.open();
     this.socket.on('eventsChanged', () => { this.monitor.updateEvents(); });
     this.socket.on('streamsChanged', () => { this.monitor.updateStreams(); });
-    /* eslint-disable-next-line node/handle-callback-err */
-    this.socket.on('error', (error) => { this.monitor.emit(Changes.ERROR.error); });
+    this.socket.on('error', (error) => { this.monitor.emit(Changes.ERROR, error); });
   }
 
   async stop () {

package/src/UpdateMethod/UpdateMethod.js

@@ -4,22 +4,24 @@
  */
 const Changes = require('../lib/Changes');
 /**
- * Interface for UpdateMonitor
+ * Base class for update methods used by Monitor.
+ * Subclass this to create custom update strategies.
  * @memberof pryv.Monitor
- * @constructor {Monitor~UpdateMethod} updateMethod.setMonitor - set only once
  */
 class UpdateMethod {
   /**
    * Assign a Monitor to this updater.
    * Usually called by the monitor itself on monitor.addUpdateMethod()
-   * @param {Monitor} monitor
+   * @param {Monitor} monitor - The monitor to attach to
    */
   setMonitor (monitor) {
     if (this.monitor) {
       throw new Error('An update Method can be assigned to one monitor only');
     }
     this.monitor = monitor;
+    // @ts-ignore - Changes.READY and Changes.STOP are valid event names
     monitor.on(Changes.READY, this.ready.bind(this));
+    // @ts-ignore
     monitor.on(Changes.STOP, this.stop.bind(this));
     if (monitor.started) {
       this.ready();
@@ -27,15 +29,15 @@ class UpdateMethod {
   }
 
   /**
-   * Should be overwritten by subclases
-   * Called with no params, when all update tasks are done.
-   * Also used at "start" call
+   * Called when all update tasks are done and monitor is ready for next update.
+   * Override in subclasses to implement custom behavior.
+   * @returns {Promise<void>}
    */
   async ready () { }
 
   /**
-   * Should be overwritten by subclases
-   * Called with no params, when monitor is stoped: updater should be stoped too.
+   * Called when monitor is stopped. Override to clean up resources.
+   * @returns {Promise<void>}
    */
   async stop () { }
 }

package/src/index.d.ts

@@ -1,28 +1,40 @@
-import pryv from 'pryv';
+import pryv, { Service, Connection, Auth, Browser, utils } from 'pryv';
 import { EventEmitter } from 'events';
 
+/**
+ * Type for the pryv library parameter - accepts both default and namespace imports
+ */
+export type PryvLibrary = {
+  Service: typeof Service;
+  Connection: typeof Connection;
+  Auth: typeof Auth;
+  Browser: typeof Browser;
+  utils: typeof utils;
+  version?: string;
+};
+
 /**
  * Extends a `pryv` instance with monitoring capabilities.
  *
  * Typical usage:
  * ```ts
  * import pryv from 'pryv';
- * import monitor from '@pryv/monitor';
+ * import extendPryvMonitor from '@pryv/monitor';
  *
  * extendPryvMonitor(pryv);
  *
- * const monitor = new pryv.Monitor('https://token@user.pryv.me', {
+ * const mon = new pryv.Monitor('https://token@user.pryv.me', {
  *   streams: ['data'],
  * });
  *
- * monitor.on(pryv.Monitor.Changes.EVENT, (event) => {
+ * mon.on(pryv.Monitor.Changes.EVENT, (event) => {
  *   // handle new or changed event
  * });
  *
- * await monitor.start();
+ * await mon.start();
  * ```
  */
-export default function extendPryvMonitor(pryvLib: typeof pryv): typeof pryv.Monitor;
+export default function extendPryvMonitor(pryvLib: PryvLibrary): typeof pryv.Monitor;
 
 declare module 'pryv' {
 
@@ -60,6 +72,9 @@ declare module 'pryv' {
   export class Monitor extends EventEmitter {
     constructor(apiEndpointOrConnection: APIEndpoint | Connection, eventsGetScope?: MonitorScope);
 
+    /** The connection used by this monitor */
+    readonly connection: Connection;
+
     /**
      * Start the monitor and perform initial sync.
      * Resolves with the same monitor instance.
@@ -93,6 +108,7 @@ declare module 'pryv' {
 
     /**
      * Attach an auto-update method implementation.
+     * @param updateMethod - The update method to use (e.g., EventsTimer, Socket)
      */
     addUpdateMethod(updateMethod: MonitorUpdateMethod): Monitor;
 
@@ -101,19 +117,18 @@ declare module 'pryv' {
      *
      * Events:
      * - `event`        – new or updated event
-     * - `eventDelete`  – deleted event
+     * - `eventDelete`  – deleted event (with id property)
      * - `streams`      – updated streams list
      * - `error`        – error object
      * - `ready`        – monitor is ready for next update
      * - `stop`         – monitor has been stopped
      */
     on(event: 'event', listener: (event: Event) => void): this;
-    on(event: 'eventDelete', listener: (event: Event) => void): this;
+    on(event: 'eventDelete', listener: (deletion: ItemDeletion) => void): this;
     on(event: 'streams', listener: (streams: Stream[]) => void): this;
-    on(event: 'error', listener: (error: any) => void): this;
+    on(event: 'error', listener: (error: Error | unknown) => void): this;
     on(event: 'ready', listener: () => void): this;
     on(event: 'stop', listener: () => void): this;
-    on(event: string, listener: (...args: any[]) => void): this;
 
     /**
      * Static access to available update methods.
@@ -128,15 +143,35 @@ declare module 'pryv' {
      * Static enum of change names.
      */
     static Changes: typeof MonitorChanges;
+
+    /** Reference to pryv library (set during extension) */
+    static pryv: typeof pryv;
   }
 
   /**
-   * Base interface for update methods used by Monitor.
+   * Base class for update methods used by Monitor.
+   * Subclass this to create custom update strategies.
    */
   export class MonitorUpdateMethod {
+    /** The monitor this update method is attached to */
     protected monitor?: Monitor;
+
+    /**
+     * Assign a Monitor to this updater.
+     * Usually called by the monitor itself on monitor.addUpdateMethod()
+     * @param monitor - The monitor to attach to
+     */
     setMonitor(monitor: Monitor): void;
+
+    /**
+     * Called when all update tasks are done and monitor is ready for next update.
+     * Override in subclasses to implement custom behavior.
+     */
     ready(): Promise<void>;
+
+    /**
+     * Called when monitor is stopped. Override to clean up resources.
+     */
     stop(): Promise<void>;
   }
 
@@ -144,13 +179,23 @@ declare module 'pryv' {
    * Update method that polls for event changes at a fixed interval.
    */
   export class EventsTimerUpdateMethod extends MonitorUpdateMethod {
+    /**
+     * @param updateRateMS - The refresh rate in milliseconds (must be > 1)
+     */
     constructor(updateRateMS: number);
+
+    /** The configured update rate in milliseconds */
+    readonly updateRateMS: number;
   }
 
   /**
-   * Update method that uses @pryv/socket.io events.
+   * Update method that uses @pryv/socket.io events for real-time updates.
+   * Requires @pryv/socket.io to be loaded.
    */
-  export class SocketUpdateMethod extends MonitorUpdateMethod {}
+  export class SocketUpdateMethod extends MonitorUpdateMethod {
+    /** The socket instance (set after ready() is called) */
+    protected socket?: SocketIO;
+  }
 }
 
 

package/src/lib/Changes.js

@@ -5,7 +5,7 @@
 /**
  * Enum trigger messages
  * @readonly
- * @enum {pryv.Monitor.Changes}
+ * @enum {string}
  */
 const Changes = {
   EVENT: 'event',

package/src/lib/updateStreams.js

@@ -7,7 +7,7 @@ const Changes = require('./Changes');
 module.exports = async function _updateStreams (monitor) {
   try {
     const result = await monitor.connection.get('streams');
-    if (!result.streams) { throw new Error('Invalid response ' + JSON.streams(result)); }
+    if (!result.streams) { throw new Error('Invalid response ' + JSON.stringify(result)); }
     monitor.emit(Changes.STREAMS, result.streams);
   } catch (e) {
     monitor.emit(Changes.ERROR, e);

package/test/load-helpers.js

@@ -3,7 +3,6 @@
  * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
  */
 /* global expect, pryv, testData */
-/* eslint-disable no-unused-expressions */
 
 require('../src')(pryv);
 const testStreamId = global.testStreamId = 'monitor-test';

package/test/monitor.test.js

@@ -28,8 +28,7 @@ describe('Monitor', function () {
     it('throw Error on invalid apiEndpoint', async () => {
       let passed = true;
       try {
-        /* eslint-disable-next-line no-unused-vars */
-        const monitor = new pryv.Monitor('BlipBlop', { limit: 1 });
+        pryv.Monitor('BlipBlop', { limit: 1 });
         passed = false;
       } catch (e) {