mastra 0.1.57-alpha.9 → 0.1.57-unstable.34

package/node_modules/express-jsdoc-swagger/index.js

@@ -0,0 +1,60 @@
+const swaggerUi = require('swagger-ui-express');
+const merge = require('merge');
+
+const defaultOptions = require('./config/default');
+const swaggerEventsOptions = require('./config/swaggerEvents');
+const processSwagger = require('./processSwagger');
+const swaggerEvents = require('./swaggerEvents');
+
+const expressJSDocSwagger = app => (userOptions = {}, userSwagger = {}) => {
+  const events = swaggerEvents(swaggerEventsOptions(userOptions));
+  const { instance } = events;
+  let swaggerObject = {};
+
+  const options = {
+    ...defaultOptions,
+    ...userOptions,
+  };
+
+  processSwagger(options, events.processFile)
+    .then(result => {
+      swaggerObject = {
+        ...swaggerObject,
+        ...result.swaggerObject,
+      };
+      swaggerObject = merge.recursive(true, swaggerObject, userSwagger);
+      events.finish(swaggerObject, {
+        jsdocInfo: result.jsdocInfo,
+        getPaths: result.getPaths,
+        getComponents: result.getComponents,
+        getTags: result.getTags,
+      });
+    })
+    .catch(events.error);
+
+  if (options.exposeSwaggerUI) {
+    app.use(options.swaggerUIPath, (req, res, next) => {
+      swaggerObject = {
+        ...swaggerObject,
+        host: req.get('host'),
+      };
+      req.swaggerDoc = swaggerObject;
+      next();
+    }, swaggerUi.serve, swaggerUi.setup(undefined, options.swaggerUiOptions));
+  }
+
+  if (options.exposeApiDocs) {
+    app.get(options.apiDocsPath, (req, res) => {
+      res.json({
+        ...swaggerObject,
+        // we skipped this as is not a valid prop in OpenAPI
+        // This is only being used in the SwaggerUI Library
+        host: undefined,
+      });
+    });
+  }
+
+  return instance;
+};
+
+module.exports = expressJSDocSwagger;

package/node_modules/express-jsdoc-swagger/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "express-jsdoc-swagger",
+  "version": "1.8.0",
+  "description": "Swagger OpenAPI 3.x generator",
+  "main": "index.js",
+  "dependencies": {
+    "chalk": "^4.1.0",
+    "doctrine": "^3.0.0",
+    "express": "^4.17.1",
+    "glob": "^7.1.6",
+    "merge": "^2.1.1",
+    "swagger-ui-express": "^4.3.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^11.0.0",
+    "@commitlint/config-conventional": "^11.0.0",
+    "eslint": "^7.19.0",
+    "eslint-config-airbnb-base": "^14.2.1",
+    "eslint-plugin-import": "^2.22.1",
+    "eslint-plugin-jest": "^24.1.3",
+    "husky": "^4.3.8",
+    "jest": "^26.6.3"
+  },
+  "engines": {
+    "node": ">= 10.0.0"
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "./node_modules/.bin/eslint ."
+  },
+  "husky": {
+    "hooks": {
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
+      "pre-commit": "npm run lint",
+      "pre-push": "npm run test"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brikev/express-jsdoc-swagger.git"
+  },
+  "keywords": [
+    "swagger",
+    "swagger-generator",
+    "express",
+    "jsdoc",
+    "node",
+    "docs",
+    "documentation",
+    "swagger-ui",
+    "OpenAPI"
+  ],
+  "author": "BRIKEV (https://github.com/brikev)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/brikev/express-jsdoc-swagger/issues"
+  },
+  "homepage": "https://brikev.github.io/express-jsdoc-swagger-docs/#/"
+}

package/node_modules/express-jsdoc-swagger/processSwagger.js

@@ -0,0 +1,45 @@
+const readFiles = require('./consumers/readFiles');
+const globFilesMatches = require('./consumers/globFilesMatches');
+const getOnlyComments = require('./consumers/getOnlyComments');
+const jsdocInfo = require('./consumers/jsdocInfo');
+const {
+  getBasicInfo,
+  getSecuritySchemes,
+  getPaths,
+  getComponents,
+  getTags,
+} = require('./transforms');
+
+const defaultLogger = () => null;
+
+const processSwagger = (options, logger = defaultLogger) => {
+  let swaggerObject = {
+    openapi: '3.0.0',
+    info: options.info,
+    servers: options.servers,
+    security: options.security,
+  };
+
+  swaggerObject = getBasicInfo(swaggerObject);
+  logger({ entity: 'basicInfo', swaggerObject });
+  swaggerObject = getSecuritySchemes(swaggerObject);
+  logger({ entity: 'securitySchemas', swaggerObject });
+
+  return globFilesMatches(options.baseDir, options.filesPattern)
+    .then(readFiles)
+    .then(getOnlyComments)
+    .then(jsdocInfo())
+    .then(data => {
+      swaggerObject = getPaths(swaggerObject, data);
+      logger({ entity: 'paths', swaggerObject });
+      swaggerObject = getComponents(swaggerObject, data, options);
+      logger({ entity: 'components', swaggerObject });
+      swaggerObject = getTags(swaggerObject, data);
+      logger({ entity: 'tags', swaggerObject });
+      return {
+        swaggerObject, jsdocInfo, getPaths, getComponents, getTags,
+      };
+    });
+};
+
+module.exports = processSwagger;

package/node_modules/express-jsdoc-swagger/swaggerEvents.js

@@ -0,0 +1,35 @@
+const { EventEmitter } = require('events');
+
+const ERROR_EVENT_NAME = 'error';
+const PROCESS_EVENT_NAME = 'process';
+const FINISH_EVENT_NAME = 'finish';
+
+let api = null;
+
+const error = eventEmitter => errorInfo => (
+  eventEmitter.emit(ERROR_EVENT_NAME, errorInfo)
+);
+
+const processFile = eventEmitter => info => (
+  eventEmitter.emit(PROCESS_EVENT_NAME, info)
+);
+
+const finish = eventEmitter => (info, methods) => (
+  eventEmitter.emit(FINISH_EVENT_NAME, info, methods)
+);
+
+const swaggerEvents = ({ multiple } = {}) => {
+  if (api && !multiple) return api;
+  const instance = new EventEmitter();
+
+  api = {
+    instance,
+    error: error(instance),
+    processFile: processFile(instance),
+    finish: finish(instance),
+  };
+
+  return api;
+};
+
+module.exports = swaggerEvents;

package/node_modules/express-jsdoc-swagger/transforms/basic/contact.js

@@ -0,0 +1,18 @@
+const setProperty = require('../utils/setProperty')('contact');
+
+const getContact = (options = {}) => ({
+  name: setProperty(options, 'name', {
+    type: 'string',
+    required: true,
+  }),
+  url: setProperty(options, 'url', {
+    type: 'string',
+    defaultValue: '',
+  }),
+  email: setProperty(options, 'email', {
+    type: 'string',
+    defaultValue: '',
+  }),
+});
+
+module.exports = getContact;

package/node_modules/express-jsdoc-swagger/transforms/basic/index.js

@@ -0,0 +1,10 @@
+const info = require('./info');
+const servers = require('./servers');
+
+const getBasicInfo = (swaggerObjet = {}) => ({
+  ...swaggerObjet,
+  info: { ...info(swaggerObjet.info) },
+  servers: servers(swaggerObjet.servers),
+});
+
+module.exports = getBasicInfo;

package/node_modules/express-jsdoc-swagger/transforms/basic/info.js

@@ -0,0 +1,26 @@
+const setProperty = require('../utils/setProperty')('info');
+const getContact = require('./contact');
+const license = require('./license');
+
+const getInfo = (options = {}) => ({
+  title: setProperty(options, 'title', {
+    type: 'string',
+    required: true,
+  }),
+  description: setProperty(options, 'description', {
+    type: 'string',
+    defaultValue: 'Add your description',
+  }),
+  ...(options.contact ? { contact: getContact(options.contact) } : {}),
+  ...(options.license ? { license: license(options.license) } : {}),
+  termsOfService: setProperty(options, 'termsOfService', {
+    type: 'string',
+    defaultValue: '',
+  }),
+  version: setProperty(options, 'version', {
+    type: 'string',
+    required: true,
+  }),
+});
+
+module.exports = getInfo;

package/node_modules/express-jsdoc-swagger/transforms/basic/license.js

@@ -0,0 +1,14 @@
+const setProperty = require('../utils/setProperty')('license');
+
+const getContact = (options = {}) => ({
+  name: setProperty(options, 'name', {
+    type: 'string',
+    required: true,
+  }),
+  url: setProperty(options, 'url', {
+    type: 'string',
+    defaultValue: '',
+  }),
+});
+
+module.exports = getContact;

package/node_modules/express-jsdoc-swagger/transforms/basic/servers.js

@@ -0,0 +1,20 @@
+const setProperty = require('../utils/setProperty')('servers');
+
+const setServer = (server = {}) => ({
+  url: setProperty(server, 'url', {
+    type: 'string',
+    required: true,
+  }),
+  description: setProperty(server, 'description', {
+    type: 'string',
+    defaultValue: '',
+  }),
+  ...(server.variables ? { variables: server.variables } : {}),
+});
+
+const setServers = (servers = []) => {
+  if (!servers || !Array.isArray(servers)) return [];
+  return servers.map(setServer);
+};
+
+module.exports = setServers;

package/node_modules/express-jsdoc-swagger/transforms/components/index.js

@@ -0,0 +1,130 @@
+const { getTagInfo, getTagsInfo } = require('../utils/tags');
+const mapDescription = require('../utils/mapDescription');
+const { refSchema, formatRefSchema } = require('../utils/refSchema');
+const addEnumValues = require('../utils/enumValues');
+const formatDescription = require('../utils/formatDescription');
+const combineSchema = require('../utils/combineSchema');
+const validateTypes = require('../utils/validateTypes');
+
+const REQUIRED = 'required';
+
+const getPropertyName = ({ name: propertyName }) => {
+  const [name] = propertyName.split('.');
+  return name;
+};
+
+const addTypeApplication = (applications, expression) => {
+  if (!applications && !expression) return {};
+  return {
+    type: expression.name.toLowerCase(),
+    items: {
+      type: applications[0].name,
+    },
+  };
+};
+
+const addRefSchema = (typeName, applications, elements) => {
+  if (!typeName && !elements) return { items: formatRefSchema(applications) };
+  return {};
+};
+
+const formatProperties = (properties, options = {}) => {
+  if (!properties || !Array.isArray(properties)) return {};
+  return properties.reduce((acum, property) => {
+    const name = getPropertyName(property);
+    const isRequired = property.name.includes(REQUIRED);
+    const {
+      name: typeName, applications, expression, elements,
+    } = property.type;
+    const [descriptionValue, enumValues, jsonOptions] = formatDescription(property.description);
+    const [description, format] = mapDescription(descriptionValue);
+    return {
+      ...acum,
+      [name]: {
+        description,
+        ...refSchema(typeName),
+        ...combineSchema(elements),
+        ...addTypeApplication(applications, expression),
+        ...addRefSchema(typeName, applications, elements),
+        ...(format ? { format } : {}),
+        ...addEnumValues(enumValues),
+
+        // Add nullable to non-required fields if option to do that is enabled
+        ...(options.notRequiredAsNullable && !isRequired ? {
+          nullable: true,
+        } : {}),
+        ...(jsonOptions || {}),
+      },
+    };
+  }, {});
+};
+
+const getRequiredProperties = properties => (
+  properties.filter(({ name }) => name.includes(REQUIRED))
+);
+
+const formatRequiredProperties = requiredProperties => requiredProperties.map(getPropertyName);
+
+const addDictionaryAdditionalProperties = typedef => {
+  if (
+    typedef.type.expression
+    && typedef.type.expression.name === 'Dictionary'
+  ) {
+    const typeName = typedef.type.applications[0].name;
+    const isPrimitive = validateTypes(typeName);
+
+    return {
+      additionalProperties: {
+        ...(isPrimitive ? { type: typeName } : { $ref: `#/components/schemas/${typeName}` }),
+      },
+    };
+  }
+
+  return {};
+};
+
+const parseSchema = (schema, options = {}) => {
+  const typedef = getTagInfo(schema.tags, 'typedef');
+  const propertyValues = getTagsInfo(schema.tags, 'property');
+  const requiredProperties = getRequiredProperties(propertyValues);
+  const [descriptionValue, enumValues, jsonOptions] = formatDescription(schema.description);
+  const [description, format] = mapDescription(descriptionValue);
+  if (!typedef || !typedef.name) return {};
+  const {
+    elements,
+  } = typedef.type;
+  const type = typedef.type.name || 'object';
+  return {
+    [typedef.name]: {
+      ...combineSchema(elements),
+      description,
+      ...(requiredProperties.length ? {
+        required: formatRequiredProperties(requiredProperties),
+      } : {}),
+      type,
+      ...(type === 'object' ? {
+        properties: formatProperties(propertyValues, options),
+      } : {}),
+      ...(format ? { format } : {}),
+      ...addEnumValues(enumValues),
+      ...addDictionaryAdditionalProperties(typedef),
+      ...(jsonOptions || {}),
+    },
+  };
+};
+
+const parseComponents = (swaggerObject = {}, components = [], options = {}) => {
+  if (!components || !Array.isArray(components)) return { components: { schemas: {} } };
+  const componentSchema = components.reduce((acum, item) => ({
+    ...acum, ...parseSchema(item, options),
+  }), {});
+  return {
+    ...swaggerObject,
+    components: {
+      ...swaggerObject.components,
+      schemas: componentSchema,
+    },
+  };
+};
+
+module.exports = parseComponents;

package/node_modules/express-jsdoc-swagger/transforms/index.js

@@ -0,0 +1,13 @@
+const getBasicInfo = require('./basic');
+const getSecuritySchemes = require('./security');
+const getPaths = require('./paths');
+const getComponents = require('./components');
+const getTags = require('./tags');
+
+module.exports = {
+  getBasicInfo,
+  getPaths,
+  getComponents,
+  getTags,
+  getSecuritySchemes,
+};

package/node_modules/express-jsdoc-swagger/transforms/paths/content.js

@@ -0,0 +1,18 @@
+const getSchema = require('./schema');
+
+const DEFAULT_CONTENT_TYPE = 'application/json';
+
+const getContent = entity => (type, contentType, originalValue, examples, extendSchema = {}) => {
+  const schema = getSchema(entity, originalValue)(type);
+  return {
+    [contentType || DEFAULT_CONTENT_TYPE]: {
+      schema: {
+        ...schema,
+        ...extendSchema,
+      },
+      ...(examples ? { examples } : {}),
+    },
+  };
+};
+
+module.exports = getContent;

package/node_modules/express-jsdoc-swagger/transforms/paths/examples.js

@@ -0,0 +1,98 @@
+const STATUS_CODES = require('./validStatusCodes');
+
+const errorMessage = require('../utils/errorMessage');
+const mapDescription = require('../utils/mapDescription');
+const generator = require('../utils/generator');
+
+const REQUEST_BODY = 'request';
+const RESPONSE_BODY = 'response';
+
+// Generates a new object with information on a request body example
+const parseRequestPayloadExample = (description, content) => {
+  const [summary] = description;
+  return {
+    type: REQUEST_BODY,
+    summary,
+    value: content,
+  };
+};
+
+const showError = message => {
+  errorMessage(message);
+  return {};
+};
+
+// Generates a new object with information on a response body example
+const parseResponsePayloadExample = (description, content) => {
+  const [status, summary] = description;
+  if (!STATUS_CODES[status]) {
+    return showError(`${status} is not a valid status for a response`);
+  }
+  return {
+    type: RESPONSE_BODY,
+    status,
+    summary,
+    value: content,
+  };
+};
+
+const getParsedExample = ({ type, metadata, content }) => {
+  const types = {
+    [REQUEST_BODY]: () => parseRequestPayloadExample(metadata, content),
+    [RESPONSE_BODY]: () => parseResponsePayloadExample(metadata, content),
+    default: () => showError(`Cannot determine where to use example of type ${type}`),
+  };
+  return (types[type] || types.default)();
+};
+
+/**
+ *  Parses a single example tag contents. Depending on the type (response or
+ * request), the expected data and returned structure will be different.
+ *
+ *  To prevent compatibility issues between SO, all `\r\n` instances (used in
+ * Windows by default as end of line sequence) will be replaced by `\n`.
+ *
+ * @param {string} exampleTagDescription - Text passed to the example tag.
+ *
+ * @return {object} Structured information about the example, including the
+ * example type (request or response), summary, status code (only applicable to
+ * response types) and the example code itself.
+ */
+const parseExample = ({ description: exampleTagDescription }) => {
+  const formattedTagDescription = exampleTagDescription.replace(/\r\n/gi, '\n');
+
+  // The example content starts right after the first end of line character
+  const contentStartIndex = formattedTagDescription.indexOf('\n');
+  const content = formattedTagDescription.substring(contentStartIndex + 1);
+  const description = formattedTagDescription.substring(0, contentStartIndex);
+
+  const [type, ...metadata] = mapDescription(description);
+
+  return getParsedExample({ type, metadata, content });
+};
+
+/**
+ *  This receives a set of values extracted from "example" tags, and translates
+ * them to objects with the example type (request or response), summary, status
+ * code (only applicable to response types) and the example code itself.
+ *
+ * @param {object[]} exampleTags - Set of example tags, which description are
+ *  expected to have the following information in order to be parsed properly:
+ *
+ *    > For request body examples:
+ *
+ *      response - [example summary]
+ *      [example content]
+ *
+ *    > For response examples:
+ *
+ *      response - [http status code] - [example summary]
+ *      [example content]
+ *
+ * @return {object[]} List of objects containing the example type (request or
+ *  response), summary, status code (only applicable to response types) and
+ *  the example code itself.
+ */
+const exampleGenerator = generator(parseExample, 'type');
+
+module.exports = exampleGenerator;

package/node_modules/express-jsdoc-swagger/transforms/paths/formParams.js

@@ -0,0 +1,40 @@
+const merge = require('merge');
+const getContent = require('./content')('@paramFormBody');
+const mapDescription = require('../utils/mapDescription');
+
+const DEFAULT_CONTENT_TYPE = 'application/json';
+
+const getRequiredValues = (currentState, contentType, key, isRequired) => {
+  const paramContentType = contentType || DEFAULT_CONTENT_TYPE;
+  if (currentState.content[paramContentType]) {
+    return [
+      ...(currentState.content[paramContentType].schema.required || []),
+      key,
+    ];
+  }
+  return isRequired ? [key] : [];
+};
+
+const formParams = (currentState, key, body, isRequired, requestExamples) => {
+  const [description, contentType] = mapDescription(body.description);
+  const schema = {
+    properties: {
+      [key]: {
+        type: body.type.name,
+        description,
+      },
+    },
+    required: getRequiredValues(currentState, contentType, key, isRequired),
+  };
+  return {
+    content: {
+      ...merge.recursive(
+        true,
+        currentState.content,
+        getContent({ name: 'object' }, contentType, description, requestExamples, schema),
+      ),
+    },
+  };
+};
+
+module.exports = formParams;