@pryv/socket.io 2.4.7 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pryv/socket.io",
-  "version": "2.4.7",
+  "version": "3.0.1",
   "description": "Extends `pryv` with Socket.IO transport",
   "keywords": [
     "Pryv",
@@ -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');
 
@@ -12,7 +11,7 @@ require('@pryv/socket.io')(pryv);
 let conn = null;
 const testStreamId = 'socket-test';
 
-describe('Socket.IO', function () {
+describe('[SKIX] Socket.IO', function () {
   this.timeout(20000);
   let apiEndpoint;
   let apiEndpointBogusToken;
@@ -41,13 +40,13 @@ describe('Socket.IO', function () {
     expect(res[0].error.id).to.equal('item-already-exists');
   });
 
-  describe('init on invalid endpoint', () => {
-    it('Should throw an error "Not Found" or ENOTFOUND when user is not known', async () => {
+  describe('[SIEX] init on invalid endpoint', () => {
+    it('[SIEA] Should throw an error "Not Found" or ENOTFOUND when user is not known', async () => {
       conn = new pryv.Connection(apiEndpointBogusUsername);
       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
@@ -59,18 +58,18 @@ describe('Socket.IO', function () {
       throw new Error('Should throw an error');
     });
 
-    it('Should throw an error "Unauthorized" when token is invalid', async () => {
+    it('[SIEB] Should throw an error "Unauthorized" when token is invalid', async () => {
       conn = new pryv.Connection(apiEndpointBogusToken);
       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');
     });
   });
 
-  describe('init on valid endpoint', () => {
+  describe('[SIVX] init on valid endpoint', () => {
     beforeEach(async () => {
       conn = new pryv.Connection(apiEndpoint);
     });
@@ -79,7 +78,7 @@ describe('Socket.IO', function () {
       conn = null;
     });
 
-    it('Should throw an error if conn.socket.api() is called before being open()', async () => {
+    it('[SIVA] Should throw an error if conn.socket.api() is called before being open()', async () => {
       try {
         await conn.socket.api([{ method: 'events.get', params: {} }]);
       } catch (e) {
@@ -88,7 +87,7 @@ describe('Socket.IO', function () {
       throw new Error('Should throw an error');
     });
 
-    it('Should throw an error if conn.socket.on() is called before being open()', async () => {
+    it('[SIVB] Should throw an error if conn.socket.on() is called before being open()', async () => {
       try {
         await conn.socket.on('eventsChanged');
       } catch (e) {
@@ -97,13 +96,13 @@ describe('Socket.IO', function () {
       throw new Error('Should throw an error');
     });
 
-    it('Correct initialization should return socket instance', async () => {
+    it('[SIVC] Correct initialization should return socket instance', async () => {
       const socket = await conn.socket.open();
       expect(socket._io).to.exist;
     });
   });
 
-  describe('socket.api', () => {
+  describe('[SAPX] socket.api', () => {
     before(async () => {
       conn = new pryv.Connection(apiEndpoint);
       await conn.socket.open();
@@ -113,7 +112,7 @@ describe('Socket.IO', function () {
       conn = null;
     });
 
-    it('Handle correctly batch calls', async () => {
+    it('[SAPA] Handle correctly batch calls', async () => {
       const res = await conn.socket.api([{ method: 'streams.get', params: {} }]);
       expect(res[0]).to.exist;
       expect(res[0].streams).to.exist;
@@ -122,7 +121,7 @@ describe('Socket.IO', function () {
     // we don't test further .api() as it relies on the implementation of pryv.Connection
   });
 
-  describe('notification', () => {
+  describe('[SNTX] notification', () => {
     before(async () => {
       conn = new pryv.Connection(apiEndpoint);
       await conn.socket.open();
@@ -132,7 +131,7 @@ describe('Socket.IO', function () {
       conn = null;
     });
 
-    it('Fails on requesting an invalid notifcation', async () => {
+    it('[SNTA] Fails on requesting an invalid notifcation', async () => {
       try {
         conn.socket.on('Bogus', () => {});
       } catch (e) {
@@ -141,7 +140,7 @@ describe('Socket.IO', function () {
       throw new Error('Should fail');
     });
 
-    it('Catches eventChanges', (done) => {
+    it('[SNTB] Catches eventChanges', (done) => {
       function onEventChanged () {
         return done();
       }
@@ -149,7 +148,7 @@ describe('Socket.IO', function () {
       conn.api([{ method: 'events.create', params: { type: 'note/txt', streamId: testStreamId, content: 'hello' } }]);
     });
 
-    it('Catches streamChanges', (done) => {
+    it('[SNTC] Catches streamChanges', (done) => {
       function onStreamChange () {
         return done();
       }
@@ -158,7 +157,7 @@ describe('Socket.IO', function () {
     });
 
     /** Keep this test the last on of this sequence */
-    it('Catches disconnect', (done) => {
+    it('[SNTD] Catches disconnect', (done) => {
       function onDisconnect (reason) {
         expect(reason).to.equal('io client disconnect');
         return done();