wip: jsdocs

Author: mikuso

index.js

@@ -1,9 +1,9 @@
-import RPCClient from './lib/client';
-import RPCServer from './lib/server';
-import errors from './lib/errors';
-import symbols from './lib/symbols';
-import { createRPCError } from './lib/util';
-import { createValidator } from './lib/validator';
+import RPCClient from './lib/client.js';
+import RPCServer from './lib/server.js';
+import errors from './lib/errors.js';
+import symbols from './lib/symbols.js';
+import { createRPCError } from './lib/util.js';
+import { createValidator } from './lib/validator.js';
 
 export default {
     RPCServer,

jsconfig.json

@@ -1,11 +1,11 @@
 {
     "compilerOptions": {
-        "target": "ES2022",
-        "module": "NodeNext",
-        "moduleResolution": "nodenext",
+        "target": "es2022",
+        "module": "node16",
+        "moduleResolution": "node16",
         "resolveJsonModule": true,
         "checkJs": true,
-        "strict": false
+        "strict": true
     },
     "exclude": [
         "node_modules/**"

lib/client.js

@@ -17,6 +17,12 @@ const MSG_CALL = 2;
 const MSG_CALLRESULT = 3;
 const MSG_CALLERROR = 4;
 
+
+/**
+ * @typedef {object} RPCClientOptions
+ * @prop {URL | string} endpoint
+ */
+
 /**
  * @typedef {CONNECTING | OPEN | CLOSING | CLOSED} ConnectionState
  */
@@ -521,10 +527,11 @@ class RPCClient extends EventEmitter {
             try {
                 await new Promise((resolve, reject) => {
                     this._ws.once('unexpected-response', (request, response) => {
-                        const err = new UnexpectedHttpResponse(response.statusMessage);
-                        err.code = response.statusCode;
-                        err.request = request;
-                        err.response = response;
+                        const err = new UnexpectedHttpResponse(response.statusMessage, {
+                            code: response.statusCode,
+                            request,
+                            response,
+                        });
                         reject(err);
                     });
                     this._ws.once('upgrade', (response) => {

lib/errors.d.ts

@@ -1,71 +1,148 @@
 
-export class TimeoutError extends Error {};
-export class UnexpectedHttpResponse extends Error {};
+export class TimeoutError extends Error {
+
+};
+
+export class UnexpectedHttpResponse extends Error {
+
+    /**
+     * An error which occurs when a Websocket HTTP upgrade fails due to receiving an unexpected response from the server.
+     * 
+     * @param {string | undefined} message
+     * @param {object} obj
+     * @param {number} [obj.code]
+     * @param {import('node:http').ClientRequest} obj.request
+     * @param {import('node:http').IncomingMessage} obj.response
+     */
+    constructor(message, {code, request, response}) {
+        super(message);
+
+        /** @type {number | undefined} */
+        this.code = code;
+
+        /** @type {import('node:http').ClientRequest} */
+        this.request = request;
+
+        /** @type {import('node:http').IncomingMessage} */
+        this.response = response;
+    }
+};
 
 export class RPCError extends Error {
+    /** @const */
     rpcErrorMessage = '';
+    /** @const */
     rpcErrorCode = 'GenericError';
 }
+
 export class RPCGenericError extends RPCError {
+    /** @const */
     rpcErrorMessage = '';
+    /** @const */
     rpcErrorCode = 'GenericError';
-};
+}
+
 export class RPCNotImplementedError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Requested method is not known';
+    /** @const */
     rpcErrorCode = 'NotImplemented';
-};
+}
+
 export class RPCNotSupportedError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Requested method is recognised but not supported';
+    /** @const */
     rpcErrorCode = 'NotSupported';
-};
+}
+
 export class RPCInternalError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'An internal error occurred and the receiver was not able to process the requested method successfully';
+    /** @const */
     rpcErrorCode = 'InternalError';
-};
+}
+
 export class RPCProtocolError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload for method is incomplete';
+    /** @const */
     rpcErrorCode = 'ProtocolError';
-};
+}
+
 export class RPCSecurityError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'During the processing of method a security issue occurred preventing receiver from completing the method successfully';
+    /** @const */
     rpcErrorCode = 'SecurityError';
-};
+}
+
 export class RPCFormatViolationError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload for the method is syntactically incorrect or not conform the PDU structure for the method';
+    /** @const */
     rpcErrorCode = 'FormatViolation';
-};
+}
+
 export class RPCFormationViolationError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload for the method is syntactically incorrect or not conform the PDU structure for the method';
+    /** @const */
     rpcErrorCode = 'FormationViolation';
-};
+}
+
 export class RPCPropertyConstraintViolationError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload is syntactically correct but at least one field contains an invalid value';
+    /** @const */
     rpcErrorCode = 'PropertyConstraintViolation';
-};
+}
+
 export class RPCOccurenceConstraintViolationError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload for the method is syntactically correct but at least one of the fields violates occurence constraints';
+    /** @const */
     rpcErrorCode = 'OccurenceConstraintViolation';
-};
+}
+
 export class RPCOccurrenceConstraintViolationError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload for the method is syntactically correct but at least one of the fields violates occurence constraints';
+    /** @const */
     rpcErrorCode = 'OccurrenceConstraintViolation';
-};
+}
+
 export class RPCTypeConstraintViolationError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Payload for the method is syntactically correct but at least one of the fields violates data type constraints';
+    /** @const */
     rpcErrorCode = 'TypeConstraintViolation';
-};
+}
+
 export class RPCMessageTypeNotSupportedError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'A message with a Message Type Number received is not supported by this implementation.';
+    /** @const */
     rpcErrorCode = 'MessageTypeNotSupported';
-};
+}
+
 export class RPCFrameworkError extends RPCError {
+    /** @const */
     rpcErrorMessage = 'Content of the call is not a valid RPC Request, for example: MessageId could not be read.';
+    /** @const */
     rpcErrorCode = 'RpcFrameworkError';
-};
+}
 
 export class WebsocketUpgradeError extends Error {
+    /**
+     * 
+     * @param {number} code 
+     * @param {string} [message] 
+     */
     constructor(code, message) {
         super(message);
+
+        /** @type {number} */
         this.code = code;
     }
 }

lib/errors.js

@@ -1,20 +1,39 @@
 
-class EventBuffer {
+/**
+ * A util class to buffer events fired by an emitter.
+ */
+export class EventBuffer {
+
+    /**
+     * @param {import("node:events").EventEmitter} emitter 
+     * @param {string | symbol} event 
+     */
     constructor(emitter, event) {
+        /** @type {import("node:events").EventEmitter} */
         this._emitter = emitter;
+
+        /** @type {string | symbol} */
         this._event = event;
 
+        /**
+         * @param  {...*} args Event data
+         */
         this._collecter = (...args) => {
             this._buffer.push(args);
         };
+
+        /** @type {*[]} */
         this._buffer = [];
         this._emitter.on(event, this._collecter);
     }
 
+    /**
+     * Returns the collected event data.
+     * 
+     * @returns {*[]}
+     */
     condense() {
         this._emitter.off(this._event, this._collecter);
         return this._buffer;
     }
 }
-
-export default EventBuffer;