Fixing types and jsdoc

Author: perki

CHANGELOG.md

@@ -2,8 +2,9 @@
 
 <!-- Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) -->
 
-
-## [Unreleased](https://github.com/pryv/lib-js/compare/2.4.5...HEAD)
+## [3.0.0](https://github.com/pryv/lib-js/compare/2.4.5...3.0.0)
+- Removing superagent dependency (breaking change)
+- Enhancing test suite
 
 ## [2.4.5](https://github.com/pryv/lib-js/compare/2.3.1...2.4.5)
 - Enhanced typescripts definition

components/pryv/src/Auth/AuthController.js

@@ -7,13 +7,15 @@ const AuthStates = require('./AuthStates');
 const Messages = require('./LoginMessages');
 
 /**
- * @private
+ * Controller for authentication flow
+ * @memberof pryv.Auth
  */
 class AuthController {
   /**
-   *
-   * @param {*} settings
-   * @param {*} service
+   * Create an AuthController
+   * @param {AuthSettings} settings - Authentication settings
+   * @param {Service} service - Pryv service instance
+   * @param {CustomLoginButton} loginButton - Login button implementation
    */
   constructor (settings, service, loginButton) {
     this.settings = settings;
@@ -50,9 +52,8 @@ class AuthController {
   }
 
   /**
-   * async function to call right after instanciating object
-   *
-   * @returns {Service}
+   * Initialize the auth controller. Call this right after instantiation.
+   * @returns {Promise<Service>} Promise resolving to the Service instance
    */
   async init () {
     this.serviceInfo = this.service.infoSync();
@@ -87,7 +88,8 @@ class AuthController {
   }
 
   /**
-   * Triggered when button is pressed
+   * Handle button click - triggers appropriate action based on current state
+   * @returns {Promise<void>}
    */
   async handleClick () {
     if (isAuthorized.call(this)) {
@@ -113,11 +115,12 @@ class AuthController {
   }
 
   /**
-   * Used only to retrieve returnUrl in browser environments
-   *
-   * @param {*} returnURL
-   * @param {*} windowLocationForTest
-   * @param {*} navigatorForTests
+   * Compute the return URL for authentication redirect.
+   * Used only in browser environments.
+   * @param {string} [returnURL] - The return URL setting ('auto#', 'self#', or custom URL)
+   * @param {string} [windowLocationForTest] - Mock window.location.href for testing
+   * @param {string|Navigator} [navigatorForTests] - Mock navigator for testing
+   * @returns {string|boolean} The computed return URL, or false if using popup mode
    */
   getReturnURL (
     returnURL,
@@ -154,6 +157,10 @@ class AuthController {
     }
   }
 
+  /**
+   * Start the authentication request and polling process
+   * @returns {Promise<void>}
+   */
   async startAuthRequest () {
     this.state = await postAccess.call(this);
 

components/pryv/src/Connection.js

@@ -51,10 +51,9 @@ class Connection {
   }
 
   /**
-   * get username.
-   * It's async as in it constructed from access info
-   * @param {*} arrayOfAPICalls
-   * @param {*} progress
+   * Get username for this connection.
+   * It's async as it's constructed from access info.
+   * @returns {Promise<string>} Promise resolving to the username
    */
   async username () {
     const accessInfo = await this.accessInfo();
@@ -67,8 +66,9 @@ class Connection {
   }
 
   /**
-   * get access info
-   * It's async as it is constructed with get function.
+   * Get access info for this connection.
+   * It's async as it is fetched from the API.
+   * @returns {Promise<AccessInfo>} Promise resolving to the access info
    */
   async accessInfo () {
     return this.get('access-info', null);
@@ -94,11 +94,12 @@ class Connection {
   }
 
   /**
-   * Make one api Api call
-   * @param {string} method - methodId
-   * @param {Object|Array} [params] - the params associated with this methodId
-   * @param {string} [resultKey] - if given, returns the value or throws an error if not present
-   * @throws {Error} if .error is present the response
+   * Make one API call
+   * @param {string} method - Method ID (e.g., 'events.get', 'streams.create')
+   * @param {Object|Array} [params={}] - The params associated with this method
+   * @param {string} [expectedKey] - If given, returns the value of this key or throws an error if not present
+   * @returns {Promise<Object>} Promise resolving to the API result or the value of expectedKey
+   * @throws {Error} If .error is present in the response or expectedKey is missing
    */
   async apiOne (method, params = {}, expectedKey) {
     const result = await this.api([{ method, params }]);
@@ -122,9 +123,10 @@ class Connection {
 
   /**
    * Revoke : Delete the accessId
-   * - Do not thow error if access is already revoked, just return null;
-   * @param {boolean} [throwOnFail = true] - if set to false do not throw Error on failure
-   * @param {Connection} [usingConnection] - specify which connection issues the revoke, might be necessary when selfRovke
+   * - Do not throw error if access is already revoked, just return null;
+   * @param {boolean} [throwOnFail=true] - if set to false do not throw Error on failure
+   * @param {Connection} [usingConnection] - specify which connection issues the revoke, might be necessary when selfRevoke
+   * @returns {Promise<Object|null>} Promise resolving to deletion result or null if already revoked/failed
    */
   async revoke (throwOnFail = true, usingConnection) {
     usingConnection = usingConnection || this;
@@ -212,33 +214,38 @@ class Connection {
   }
 
   /**
-   * Post to API return results
-   * @param {(Array | Object)} data
-   * @param {string} path
-   * @returns {Promise<Array|Object>} Promise to result.body
+   * Post to API and return results
+   * @param {string} path - API path
+   * @param {(Array | Object)} data - Data to post
+   * @returns {Promise<Object|Object[]>} Promise to result.body
    */
   async post (path, data) {
     const now = getTimestamp();
-    const res = await this.postFetch(path, data);
+    const res = await this._postFetch(path, data);
     this._handleMeta(res.body, now);
     return res.body;
   }
 
   /**
+   * @private
    * Post object as JSON to API
-   * @param {Array | Object} data
-   * @param {string} path
+   * @param {string} path - API path
+   * @param {Array | Object} data - Data to post as JSON
+   * @returns {Promise<{response: Response, body: Object|Object[]}>} Promise to response and body
    */
-  async postFetch (path, data) {
-    return this.postFetchRaw(path, JSON.stringify(data), 'application/json');
+  async _postFetch (path, data) {
+    return this._postFetchRaw(path, JSON.stringify(data), 'application/json');
   }
 
   /**
+   * @private
    * Raw Post to API
-   * @param {Array | Object} data
-   * @param {string} path
+   * @param {string} path - API path
+   * @param {any} data - Raw data to post
+   * @param {string} [contentType] - Content-Type header (optional, allows fetch to set it for FormData)
+   * @returns {Promise<{response: Response, body: Object|Object[]}>} Promise to response and body
    */
-  async postFetchRaw (path, data, contentType) {
+  async _postFetchRaw (path, data, contentType) {
     const headers = {
       Authorization: this.token,
       Accept: 'application/json'
@@ -258,23 +265,26 @@ class Connection {
   }
 
   /**
-   * Post to API return results
-   * @param {Object} queryParams
-   * @param {string} path
-   * @returns {Promise<Array|Object>}  Promise to result.body
+   * GET from API and return results
+   * @param {string} path - API path
+   * @param {Object} [queryParams] - Query parameters
+   * @returns {Promise<Object|Object[]>} Promise to result.body
    */
   async get (path, queryParams) {
     const now = getTimestamp();
-    const res = await this.getFetchRaw(path, queryParams);
+    const res = await this._getFetchRaw(path, queryParams);
     this._handleMeta(res.body, now);
     return res.body;
   }
 
   /**
-   * @param {Object} queryParams
-   * @param {string} path
+   * @private
+   * Raw GET from API
+   * @param {string} path - API path
+   * @param {Object} [queryParams={}] - Query parameters
+   * @returns {Promise<{response: Response, body: Object|Object[]}>} Promise to response and body
    */
-  async getFetchRaw (path, queryParams = {}) {
+  async _getFetchRaw (path, queryParams = {}) {
     path = path || '';
     let queryStr = '';
     if (queryParams && Object.keys(queryParams).length > 0) {
@@ -344,7 +354,7 @@ class Connection {
     formData.append('file', fileBlob, fileName);
 
     const now = getTimestamp();
-    const { body } = await this.postFetchRaw('events', formData);
+    const { body } = await this._postFetchRaw('events', formData);
     this._handleMeta(body, now);
     return body;
   }
@@ -375,7 +385,7 @@ class Connection {
    */
   async createEventWithFormData (event, formData) {
     formData.append('event', JSON.stringify(event));
-    const { body } = await this.postFetchRaw('events', formData);
+    const { body } = await this._postFetchRaw('events', formData);
     return body;
   }
 
@@ -390,9 +400,9 @@ class Connection {
   }
 
   /**
-   * API endpoint of this connection
+   * API endpoint of this connection (includes token if present)
    * @readonly
-   * @property {APIEndpoint} deltaTime
+   * @property {APIEndpoint} apiEndpoint
    */
   get apiEndpoint () {
     return utils.buildAPIEndpoint(this);

components/pryv/src/Service.js

@@ -70,16 +70,16 @@ class Service {
 
   /**
    * Check if a service supports High Frequency Data Sets
-   * @return true if yes
+   * @returns {Promise<boolean>} Promise resolving to true if HF is supported
    */
   async supportsHF () {
     const infos = await this.info();
     return (infos.features == null || infos.features.noHF !== true);
   }
 
   /**
-   * Check if a service has username in the hostname or in the path of the api
-   * @return true if the service does not rely on DNS to find a host related to a username
+   * Check if a service has username in the hostname or in the path of the API.
+   * @returns {Promise<boolean>} Promise resolving to true if the service does not rely on DNS to find a host related to a username
    */
   async isDnsLess () {
     const infos = await this.info();
@@ -134,22 +134,22 @@ class Service {
 
   /**
    * Return an API endpoint from a username and token
-   * @param {string} username
-   * @param {string} [token]
-   * @return {APIEndpoint}
+   * @param {string} username - The username
+   * @param {string} [token] - Optional authorization token
+   * @returns {Promise<APIEndpoint>} Promise resolving to the API endpoint URL
    */
   async apiEndpointFor (username, token) {
     const serviceInfo = await this.info();
     return Service.buildAPIEndpoint(serviceInfo, username, token);
   }
 
   /**
-   * Return an API endpoint from a username and token and a ServiceInfo.
-   * This is method is rarely used. See **apiEndpointFor** as an alternative.
-   * @param {ServiceInfo} serviceInfo
-   * @param {string} username
-   * @param {string} [token]
-   * @return {APIEndpoint}
+   * Return an API endpoint from a username, token and ServiceInfo.
+   * This method is rarely used. See **apiEndpointFor** as an alternative.
+   * @param {ServiceInfo} serviceInfo - The service info object containing API URL template
+   * @param {string} username - The username
+   * @param {string} [token] - Optional authorization token
+   * @returns {APIEndpoint} The constructed API endpoint URL
    */
   static buildAPIEndpoint (serviceInfo, username, token) {
     const endpoint = serviceInfo.api.replace('{username}', username);

components/pryv/src/ServiceAssets.js

@@ -25,9 +25,9 @@ class ServiceAssets {
   }
 
   /**
-   * Load Assets definition
-   * @param {string} pryvServiceAssetsSourceUrl
-   * @returns {ServiceAssets}
+   * Load Assets definition from URL
+   * @param {string} pryvServiceAssetsSourceUrl - URL to the assets definition JSON
+   * @returns {Promise<ServiceAssets>} Promise resolving to ServiceAssets instance
    */
   static async setup (pryvServiceAssetsSourceUrl) {
     const { body } = await utils.fetchGet(pryvServiceAssetsSourceUrl);
@@ -110,6 +110,7 @@ class ServiceAssets {
 
   /**
    * Get HTML for Login Button
+   * @returns {Promise<string>} Promise resolving to HTML string
    */
   async loginButtonGetHTML () {
     const { text } = await utils.fetchGetText(this.relativeURL(this._assets['lib-js'].buttonSignIn.html));
@@ -118,6 +119,7 @@ class ServiceAssets {
 
   /**
    * Get Messages strings for Login Button
+   * @returns {Promise<Object.<string, string>>} Promise resolving to messages object
    */
   async loginButtonGetMessages () {
     const { body } = await utils.fetchGet(this.relativeURL(this._assets['lib-js'].buttonSignIn.messages));