feat: Add types for typescript (#116)

.github/workflows/release.yml

@@ -22,6 +22,8 @@ jobs:
         run: npm test
       - name: Regenerate docs
         run: npm run docs
+      - name: Regenerate types
+        run: npm run types
       - name: Generate bundle.js for the browser
         run: npm run prepublishOnly
       - name: Get version from package.json before release step

lib/asyncapiSchemaFormatParser.js

@@ -8,6 +8,9 @@ module.exports = {
   getMimeTypes
 };
 
+/**
+ * @private
+ */
 async function parse({ message, originalAsyncAPIDocument, fileFormat, parsedAsyncAPIDocument, pathToPayload }) {
   const ajv = new Ajv({
     jsonPointers: true,
@@ -27,6 +30,9 @@ async function parse({ message, originalAsyncAPIDocument, fileFormat, parsedAsyn
   });
 }
 
+/**
+ * @private
+ */
 function getMimeTypes() {
   return [
     'application/vnd.aai.asyncapi;version=2.0.0',
@@ -42,6 +48,7 @@ function getMimeTypes() {
  * To validate schema of the payload we just need a small portion of official AsyncAPI spec JSON Schema, the definition of the schema must be
  * a main part of the JSON Schema
  * 
+ * @private
  * @param  {Object} asyncapiSchema AsyncAPI specification JSON Schema
  * @returns {Object} valid JSON Schema document describing format of AsyncAPI-valid schema for message payload
  */
@@ -56,6 +63,7 @@ function preparePayloadSchema(asyncapiSchema) {
  * Errors from Ajv contain dataPath information about parameter relative to parsed payload message. 
  * This function enriches dataPath with additional information on where is the parameter located in AsyncAPI document
  * 
+ * @private
  * @param  {Array<Object>} errors Ajv errors
  * @param  {String} path Path to location of the payload schema in AsyncAPI Document
  * @returns {Array<Object>} same object as received in input but with modified datePath property so it contain full path relative to AsyncAPI document

lib/customValidators.js

@@ -4,7 +4,7 @@ const validationError = 'validation-errors';
 
 /**
  * Validates if variables provided in the url have corresponding variable object defined
- * 
+ * @private
  * @param  {Object} parsedJSON parsed AsyncAPI document
  * @param  {String} asyncapiYAMLorJSON AsyncAPI document in string
  * @param  {String} initialFormat information of the document was oryginally JSON or YAML
@@ -46,6 +46,7 @@ function validateServerVariables(parsedJSON, asyncapiYAMLorJSON, initialFormat)
 /**
  * Validates if parameters specified in the channel have corresponding parameters object defined
  * 
+ * @private
  * @param  {Object} parsedJSON parsed AsyncAPI document
  * @param  {String} asyncapiYAMLorJSON AsyncAPI document in string
  * @param  {String} initialFormat information of the document was oryginally JSON or YAML
@@ -88,6 +89,7 @@ function validateChannelParams(parsedJSON, asyncapiYAMLorJSON, initialFormat) {
 /**
  * Validates if operationIds are duplicated in the document
  * 
+ * @private
  * @param  {Object} parsedJSON parsed AsyncAPI document
  * @param  {String} asyncapiYAMLorJSON AsyncAPI document in string
  * @param  {String} initialFormat information of the document was oryginally JSON or YAML
@@ -136,10 +138,11 @@ function validateOperationId(parsedJSON, asyncapiYAMLorJSON, initialFormat, oper
 /**
  * Validates if server security is declared properly and the name has a corresponding security schema definition in components with the same name
  * 
+ * @private
  * @param  {Object} parsedJSON parsed AsyncAPI document
  * @param  {String} asyncapiYAMLorJSON AsyncAPI document in string
  * @param  {String} initialFormat information of the document was oryginally JSON or YAML
- * @param  {Array[String]} specialSecTypes list of security types that can have data in array
+ * @param  {String[]} specialSecTypes list of security types that can have data in array
  * @returns {Boolean} true in case the document is valid, otherwise throws ParserError
  */
 function validateServerSecurity(parsedJSON, asyncapiYAMLorJSON, initialFormat, specialSecTypes) {
@@ -196,7 +199,7 @@ function validateServerSecurity(parsedJSON, asyncapiYAMLorJSON, initialFormat, s
  * @private
  * @param  {String} securityName name of the server security element that you want to localize in the security schema object
  * @param  {Object} components components object from the AsyncAPI document
- * @returns {Array[String]} there are 2 elements in array, index 0 is the name of the security schema object and index 1 is it's type
+ * @returns {String[]} there are 2 elements in array, index 0 is the name of the security schema object and index 1 is it's type
  */
 function findSecuritySchema(securityName, components) {
   const secSchemes =  components && components.securitySchemes;
@@ -217,10 +220,10 @@ function findSecuritySchema(securityName, components) {
  * Validates if given server security is a proper empty array when security type requires it
  * @private
  * @param  {String} schemaType security type, like httpApiKey or userPassword
- * @param  {Array[String]} specialSecTypes list of special types that do not have to be an empty array
+ * @param  {String[]} specialSecTypes list of special types that do not have to be an empty array
  * @param  {Object} secObj server security object
  * @param  {String} secName name os server security object
- * @returns {Array[String]} there are 2 elements in array, index 0 is the name of the security schema object and index 1 is it's type
+ * @returns {String[]} there are 2 elements in array, index 0 is the name of the security schema object and index 1 is it's type
  */
 function isSrvrSecProperArray(schemaType, specialSecTypes, secObj, secName) {
   if (!specialSecTypes.includes(schemaType)) {
@@ -237,4 +240,4 @@ module.exports = {
   validateServerVariables,
   validateOperationId,
   validateServerSecurity
-};
+};

lib/errors/parser-error.js

@@ -13,6 +13,8 @@ const buildError = (from, to) => {
 
 /**
  * Represents an error while trying to parse an AsyncAPI document.
+ * @alias module:@asyncapi/parser#ParserError
+ * @extends Error
  */
 class ParserError extends Error {
   /**

lib/models/asyncapi.js

@@ -12,7 +12,8 @@ const xParserCircle = 'x-parser-circular';
 
 /**
  * Implements functions to deal with the AsyncAPI document.
- * @class
+ * @class 
+ * @alias module:@asyncapi/parser#AsyncAPIDocument
  * @extends Base
  * @returns {AsyncAPIDocument}
  */
@@ -146,7 +147,7 @@ class AsyncAPIDocument extends Base {
   }
 
   /**
-   * @returns {Map<Message>}
+   * @returns {Map<string, Message>}
    */
   allMessages() {
     const messages = new Map();
@@ -177,7 +178,7 @@ class AsyncAPIDocument extends Base {
   }
 
   /**
-   * @returns {Map<Schema>}
+   * @returns {Map<string, Schema>}
    */
   allSchemas() {
     const schemas = new Map();
@@ -204,6 +205,12 @@ class AsyncAPIDocument extends Base {
   }
 }
 
+/**
+ * Assign message keys as message name to all the component messages.
+ * 
+ * @private
+ * @param {AsyncAPIDocument} doc 
+ */
 function assignNameToComponentMessages(doc) {
   if (doc.hasComponents()) {
     for (const [key, m] of Object.entries(doc.components().messages())) {
@@ -217,6 +224,7 @@ function assignNameToComponentMessages(doc) {
 /**
  * Assign parameter keys as uid for the parameter schema.
  * 
+ * @private
  * @param {AsyncAPIDocument} doc 
  */
 function assignUidToParameterSchemas(doc) {
@@ -231,6 +239,7 @@ function assignUidToParameterSchemas(doc) {
 /**
  * Assign uid to component schemas. 
  * 
+ * @private
  * @param {AsyncAPIDocument} doc 
  */
 function assignUidToComponentSchemas(doc) {
@@ -244,6 +253,7 @@ function assignUidToComponentSchemas(doc) {
 /**
  * Assign anonymous names to nameless messages.
  * 
+ * @private
  * @param {AsyncAPIDocument} doc 
  */
 function assignNameToAnonymousMessages(doc) {
@@ -261,7 +271,8 @@ function assignNameToAnonymousMessages(doc) {
 /**
  * Add anonymous name to key if no name provided.
  * 
- * @param {messages} map of messages 
+ * @private
+ * @param {Message} map of messages 
  */
 function addNameToKey(messages, number) {
   messages.forEach(m => {
@@ -273,7 +284,7 @@ function addNameToKey(messages, number) {
 
 /**
  * Function that indicates that a circular reference was detected.
- * 
+ * @private
  * @param {Schema} schema schema that is currently accessed and need to be checked if it is a first time
  * @param {Array} seenObjects list of objects that were already seen during recursion 
  */
@@ -284,18 +295,25 @@ function isCircular(schema, seenObjects) {
 /**
  * Mark schema as being a circular ref
  * 
+ * @private
  * @param {Schema} schema schema that should be marked as circular
  */
 function markCircular(schema) {
   schema.json()[String(xParserCircle)] = true;
 }
+
+/**
+ * Callback that is called foreach schema found
+ * @private
+ * @callback FoundSchemaCallback
+ * @param {Schema} schema found.
+*/
 /**
  * Recursively go through each schema and execute callback.
  * 
- * @param {Schema} schemaContent schema.
- * @param {Function} callback(schema)
- *         the function that is called foreach schema found.
- *         schema {Schema}: the found schema.
+ * @private
+ * @param {Schema} schema found.
+ * @param {FoundSchemaCallback} callback
  */
 function recursiveSchema(schemaContent, callback) {
   if (schemaContent === null) return;
@@ -307,6 +325,7 @@ function recursiveSchema(schemaContent, callback) {
 /**
  * Schema crawler
  * 
+ * @private
  * @param {Schema} schemaContent schema.
  * @param {Array} seenObj schema elements that crowler went through already.
  * @param {Function} callback(schema)
@@ -345,10 +364,9 @@ function crawl(schema, seenObj, callback) {
 /**
  * Go through each channel and for each parameter, and message payload and headers recursively call the callback for each schema.
  * 
+ * @private
  * @param {AsyncAPIDocument} doc 
- * @param {Function} callback(schema)
- *         the function that is called foreach schema found.
- *         schema {Schema}: the found schema.
+ * @param {FoundSchemaCallback} callback
  */
 function schemaDocument(doc, callback) {
   if (doc.hasChannels()) {
@@ -378,6 +396,7 @@ function schemaDocument(doc, callback) {
 /**
  * Gives schemas id to all anonymous schemas.
  * 
+ * @private
  * @param {AsyncAPIDocument} doc 
  */
 function assignIdToAnonymousSchemas(doc) {
@@ -393,6 +412,7 @@ function assignIdToAnonymousSchemas(doc) {
 /**
  * Recursively go through schema of object type and execute callback.
  * 
+ * @private
  * @param {Schema} schema Object type.
  * @param {Array} seenObj schema elements that crawler went through already.
  * @param {Function} callback(schema)
@@ -415,6 +435,7 @@ function recursiveSchemaObject(schema, seenObj, callback) {
 /**
  * Recursively go through schema of array type and execute callback.
  * 
+ * @private
  * @param {Schema} schema Array type.
  * @param {Array} seenObj schema elements that crowler went through already.
  * @param {Function} callback(schema)

lib/models/base.js

@@ -3,6 +3,7 @@ const ParserError = require('../errors/parser-error');
 /**
  * Implements common functionality for all the models.
  * @class
+ * @alias module:@asyncapi/parser#Base
  * @returns {Base}
  */
 class Base {

lib/models/channel-parameter.js

@@ -5,6 +5,7 @@ const Schema = require('./schema');
 /**
  * Implements functions to deal with a ChannelParameter object.
  * @class
+ * @alias module:@asyncapi/parser#ChannelParameter
  * @extends Base
  * @returns {ChannelParameter}
  */

lib/models/channel.js

@@ -7,6 +7,7 @@ const SubscribeOperation = require('./subscribe-operation');
 /**
  * Implements functions to deal with a Channel object.
  * @class
+ * @alias module:@asyncapi/parser#Channel
  * @extends Base
  * @returns {Channel}
  */

lib/models/components.js

@@ -11,6 +11,7 @@ const MessageTrait = require('./message-trait');
 /**
  * Implements functions to deal with a Components object.
  * @class
+ * @alias module:@asyncapi/parser#Components
  * @extends Base
  * @returns {Components}
  */

lib/models/contact.js

@@ -4,6 +4,7 @@ const Base = require('./base');
 /**
  * Implements functions to deal with the Contact object.
  * @class
+ * @alias module:@asyncapi/parser#Contact
  * @extends Base
  * @returns {Contact}
  */

lib/models/correlation-id.js

@@ -4,6 +4,7 @@ const Base = require('./base');
 /**
  * Implements functions to deal with a CorrelationId object.
  * @class
+ * @alias module:@asyncapi/parser#CorrelationId
  * @extends Base
  * @returns {CorrelationId}
  */

lib/models/external-docs.js

@@ -4,6 +4,7 @@ const Base = require('./base');
 /**
  * Implements functions to deal with an ExternalDocs object.
  * @class
+ * @alias module:@asyncapi/parser#ExternalDocs
  * @extends Base
  * @returns {ExternalDocs}
  */

lib/models/info.js

@@ -5,7 +5,8 @@ const Contact = require('./contact');
 
 /**
  * Implements functions to deal with the Info object.
- * @class Info
+ * @class 
+ * @alias module:@asyncapi/parser#Info
  * @extends Base
  * @returns {Info}
  */

lib/models/license.js

@@ -4,6 +4,7 @@ const Base = require('./base');
 /**
  * Implements functions to deal with the License object.
  * @class
+ * @alias module:@asyncapi/parser#License
  * @extends Base
  * @returns {License}
  */

lib/models/message-trait.js

@@ -4,6 +4,7 @@ const MessageTraitable = require('./message-traitable');
 /**
  * Implements functions to deal with a MessageTrait object.
  * @class
+ * @alias module:@asyncapi/parser#MessageTrait
  * @extends Base
  * @returns {MessageTrait}
  */

lib/models/message-traitable.js

@@ -8,6 +8,7 @@ const CorrelationId = require('./correlation-id');
 /**
  * Implements functions to deal with a the common properties that Message and MessageTrait objects have.
  * @class
+ * @alias module:@asyncapi/parser#MessageTraitable
  * @extends Base
  * @returns {MessageTraitable}
  */

lib/models/message.js

@@ -4,6 +4,7 @@ const Schema = require('./schema');
 /**
  * Implements functions to deal with a Message object.
  * @class
+ * @alias module:@asyncapi/parser#Message
  * @extends MessageTraitable
  * @returns {Message}
  */

lib/models/oauth-flow.js

@@ -4,6 +4,7 @@ const Base = require('./base');
 /**
  * Implements functions to deal with a OAuthFlow object.
  * @class
+ * @alias module:@asyncapi/parser#OAuthFlow
  * @extends Base
  * @returns {OAuthFlow}
  */

lib/models/operation-trait.js

@@ -3,6 +3,7 @@ const OperationTraitable = require('./operation-traitable');
 /**
  * Implements functions to deal with a OperationTrait object.
  * @class
+ * @alias module:@asyncapi/parser#OperationTrait
  * @extends OperationTraitable
  * @returns {OperationTrait}
  */