@pryv/socket.io 2.4.6 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pryv/socket.io",
-  "version": "2.4.6",
+  "version": "3.0.0",
   "description": "Extends `pryv` with Socket.IO transport",
   "keywords": [
     "Pryv",
@@ -14,7 +14,7 @@
   },
   "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)",
@@ -22,5 +22,8 @@
   "types": "src/index.d.ts",
   "dependencies": {
     "socket.io-client": "^4.5.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   }
 }

package/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) => {
@@ -29,6 +40,7 @@ class SocketIO extends EventEmitter {
       this.connection.username()
         .then(username => {
           const socketEndpoint = this.connection.endpoint + username + '?auth=' + this.connection.token;
+          // @ts-ignore - io is callable in socket.io-client
           this._io = io(socketEndpoint, { forceNew: true });
 
           // handle failure
@@ -71,21 +83,26 @@ 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
    */
+  // @ts-ignore - overriding EventEmitter.on with restricted signature
   on (eventName, listener) {
     checkOpen(this);
     if (EVENTS.indexOf(eventName) < 0) {
       throw new Error('Unkown event [' + eventName + ']. Allowed events are: ' + EVENTS);
     }
+    // @ts-ignore
     return super.on(eventName, listener);
   }
 
   /**
-   * 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);

package/src/index.d.ts

@@ -1,6 +1,18 @@
-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 Socket.IO capabilities.
  *
@@ -18,9 +30,16 @@ import { EventEmitter } from 'events';
  * });
  * ```
  */
-export default function extendPryvSocketIO(pryvLib: typeof pryv): void;
+export default function extendPryvSocketIO(pryvLib: PryvLibrary): void;
 
 declare module 'pryv' {
+  export type SocketIOEventName =
+    | 'eventsChanged'
+    | 'streamsChanged'
+    | 'accessesChanged'
+    | 'disconnect'
+    | 'error';
+
   /**
    * Socket.IO transport for a `Connection`.
    *
@@ -30,6 +49,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 +79,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 {

package/test/socket.io.test.js

@@ -3,7 +3,6 @@
  * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
  */
 /* global describe, it, before, after, beforeEach, afterEach, expect, pryv, testData */
-/* eslint-disable no-unused-expressions */
 
 const cuid = require('cuid');
 
@@ -47,7 +46,7 @@ describe('Socket.IO', function () {
       try {
         await conn.socket.open();
       } catch (e) {
-        if (e.message === 'Not Found' || e.message.startsWith('getaddrinfo ENOTFOUND')) {
+        if (e.message === 'Not Found' || e.message.startsWith('getaddrinfo ENOTFOUND') || e.message === 'fetch failed') {
           return;
         }
         if (typeof document !== 'undefined') { // in browser
@@ -64,7 +63,7 @@ describe('Socket.IO', function () {
       try {
         await conn.socket.open();
       } catch (e) {
-        return expect(e.response.text).to.include('Cannot find access from token.');
+        return expect(e.message).to.include('Cannot find access from token.');
       }
       throw new Error('Should throw an error');
     });