Fixing modules types

Author: perki

components/pryv-monitor/src/Monitor.js

@@ -9,13 +9,16 @@ 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();
@@ -44,8 +47,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 +66,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 +98,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) {

components/pryv-monitor/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();

components/pryv-monitor/src/UpdateMethod/Socket.js

@@ -6,6 +6,12 @@
 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;

components/pryv-monitor/src/UpdateMethod/UpdateMethod.js

@@ -4,15 +4,15 @@
  */
 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) {
@@ -27,15 +27,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 () { }
 }

components/pryv-monitor/src/index.d.ts

@@ -7,19 +7,19 @@ import { EventEmitter } from 'events';
  * 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;
@@ -60,6 +60,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 +96,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 +105,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,29 +131,59 @@ 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>;
   }
 
   /**
    * 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;
+  }
 }
 
 

components/pryv-socket.io/src/SocketIO.js

@@ -7,18 +7,29 @@ const { EventEmitter } = require('events');
 
 const EVENTS = ['eventsChanged', 'streamsChanged', 'accessesChanged', 'disconnect', 'error'];
 
+/**
+ * Socket.IO transport for a Connection.
+ * Use connection.socket to access the instance associated with a Connection.
+ * @memberof pryv
+ * @extends EventEmitter
+ */
 class SocketIO extends EventEmitter {
+  /**
+   * @param {Connection} connection - The connection to bind to
+   */
   constructor (connection) {
     super();
+    /** @type {Connection} */
     this.connection = connection;
+    /** @type {boolean} */
     this.connecting = false;
     this._io = null;
   }
 
   /**
-   * Open the scocket stream
+   * Open the Socket.IO stream
    * @throws {Error} On connection failures
-   * @return {SocketIO} this
+   * @returns {Promise<SocketIO>} Promise resolving to this SocketIO instance
    */
   async open () {
     return new Promise((resolve, reject) => {
@@ -71,10 +82,10 @@ class SocketIO extends EventEmitter {
   }
 
   /**
-   * Add listner
-   * @param {string} eventName - one of 'eventsChanged', 'streamsChanged', 'accessesChanged', 'disconnect', 'error'
-   * @param {Function} listener The callback function
-   * @return {EventEmitter};
+   * Add listener for Socket.IO events
+   * @param {('eventsChanged'|'streamsChanged'|'accessesChanged'|'disconnect'|'error')} eventName - The event to listen for
+   * @param {Function} listener - The callback function
+   * @returns {SocketIO} this
    */
   on (eventName, listener) {
     checkOpen(this);
@@ -85,7 +96,10 @@ class SocketIO extends EventEmitter {
   }
 
   /**
-   * Identical to Connection.api() using socket.io transport
+   * Identical to Connection.api() but using Socket.IO transport
+   * @param {Array<MethodCall>} arrayOfAPICalls - Array of Method Calls
+   * @param {Function} [progress] - Return percentage of progress (0 - 100)
+   * @returns {Promise<Array>} Promise to Array of results matching each method call in order
    */
   async api (arrayOfAPICalls, progress) {
     checkOpen(this);

components/pryv-socket.io/src/index.d.ts

@@ -21,6 +21,13 @@ import { EventEmitter } from 'events';
 export default function extendPryvSocketIO(pryvLib: typeof pryv): void;
 
 declare module 'pryv' {
+  export type SocketIOEventName =
+    | 'eventsChanged'
+    | 'streamsChanged'
+    | 'accessesChanged'
+    | 'disconnect'
+    | 'error';
+
   /**
    * Socket.IO transport for a `Connection`.
    *
@@ -30,6 +37,12 @@ declare module 'pryv' {
   export class SocketIO extends EventEmitter {
     constructor(connection: Connection);
 
+    /** The connection this socket is bound to */
+    readonly connection: Connection;
+
+    /** True while the socket is in the process of connecting */
+    readonly connecting: boolean;
+
     /**
      * Open the Socket.IO stream.
      * @throws Error on connection failures
@@ -54,21 +67,18 @@ declare module 'pryv' {
      * Listen to Socket.IO events emitted by the Pryv.io backend.
      *
      * Supported events:
-     * - `eventsChanged`
-     * - `streamsChanged`
-     * - `accessesChanged`
-     * - `disconnect`
-     * - `error`
+     * - `eventsChanged` - Events have been modified
+     * - `streamsChanged` - Streams have been modified
+     * - `accessesChanged` - Accesses have been modified
+     * - `disconnect` - Socket disconnected
+     * - `error` - An error occurred
      */
-    on(
-      eventName:
-        | 'eventsChanged'
-        | 'streamsChanged'
-        | 'accessesChanged'
-        | 'disconnect'
-        | 'error',
-      listener: (...args: any[]) => void
-    ): this;
+    on(event: 'eventsChanged', listener: () => void): this;
+    on(event: 'streamsChanged', listener: () => void): this;
+    on(event: 'accessesChanged', listener: () => void): this;
+    on(event: 'disconnect', listener: (reason: string) => void): this;
+    on(event: 'error', listener: (error: Error | unknown) => void): this;
+    on(event: SocketIOEventName, listener: (...args: unknown[]) => void): this;
   }
 
   export class Connection {