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

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

@@ -0,0 +1,127 @@
+const examplesGenerator = require('./examples');
+const responsesGenerator = require('./responses');
+const parametersGenerator = require('./parameters');
+const requestBodyGenerator = require('./requestBody');
+const { getTagInfo, getTagsInfo, formatDescriptionTag } = require('../utils/tags');
+const {
+  validRequestBodyMethods: bodyMethods,
+  validHTTPMethod,
+} = require('../utils/httpMethods');
+const formatSecurity = require('./security');
+
+const formatTags = (tags = []) => tags.map(({ description }) => {
+  const { name } = formatDescriptionTag(description);
+  return name;
+});
+
+const formatSummary = summary => (summary || {}).description || '';
+
+const formatDescription = description => (description || {}).description || undefined;
+
+const setRequestBody = (lowerCaseMethod, bodyValues, requestExamples) => {
+  const hasBodyValues = bodyValues.length > 0;
+  const requestBody = requestBodyGenerator(requestExamples, bodyValues);
+  return bodyMethods[lowerCaseMethod] && hasBodyValues ? { requestBody } : {};
+};
+
+const bodyParams = ({ name }) => name.includes('request.body') || name.includes('.form');
+
+const getOperationId = operationIdTag => {
+  if (!operationIdTag) return {};
+  return {
+    operationId: operationIdTag.description,
+  };
+};
+
+const pathValues = tags => {
+  const examplesValues = getTagsInfo(tags, 'example');
+  const examples = examplesGenerator(examplesValues);
+
+  const summary = getTagInfo(tags, 'summary');
+  const description = getTagInfo(tags, 'description');
+  const deprecated = getTagInfo(tags, 'deprecated');
+  const isDeprecated = !!deprecated;
+  /* Response info */
+  const returnValues = [
+    ...getTagsInfo(tags, 'return'),
+    ...getTagsInfo(tags, 'returns'),
+  ];
+  const responseExamples = examples.filter(example => example.type === 'response');
+  const responses = responsesGenerator(returnValues, responseExamples);
+  /* Parameters info */
+  const operationId = getTagsInfo(tags, 'operationId');
+  const paramValues = getTagsInfo(tags, 'param');
+  const parameters = parametersGenerator(paramValues);
+  /* Tags info */
+  const tagsValues = getTagsInfo(tags, 'tags');
+  /* Security info */
+  const securityValues = getTagsInfo(tags, 'security');
+  /* Request body info */
+  const bodyValues = paramValues.filter(bodyParams);
+  return {
+    summary,
+    description,
+    isDeprecated,
+    responses,
+    parameters,
+    tagsValues,
+    bodyValues,
+    securityValues,
+    examples,
+    operationId: operationId[0],
+  };
+};
+
+const parsePath = (path, state) => {
+  if (!path.description || !path.tags) return {};
+  const [method, endpoint] = path.description.split(' ');
+  // if jsdoc comment does not contain structure <Method> - <Endpoint> is not valid path
+  const lowerCaseMethod = method.toLowerCase();
+  if (!validHTTPMethod(lowerCaseMethod)) return {};
+  const { tags } = path;
+  const {
+    summary,
+    description,
+    bodyValues,
+    isDeprecated,
+    responses,
+    parameters,
+    tagsValues,
+    securityValues,
+    examples,
+    operationId,
+  } = pathValues(tags);
+  const requestExamples = examples.filter(example => example.type === 'request');
+  return {
+    ...state,
+    [endpoint]: {
+      ...state[endpoint],
+      [lowerCaseMethod]: {
+        deprecated: isDeprecated,
+        summary: formatSummary(summary),
+        description: formatDescription(description),
+        security: formatSecurity(securityValues),
+        responses,
+        parameters,
+        tags: formatTags(tagsValues),
+        ...(setRequestBody(lowerCaseMethod, bodyValues, requestExamples)),
+        ...(getOperationId(operationId)),
+      },
+    },
+  };
+};
+
+const getPathObject = paths => paths.reduce((acum, item) => ({
+  ...acum, ...parsePath(item, acum),
+}), {});
+
+const parsePaths = (swaggerObject = {}, paths = []) => {
+  if (!paths || !Array.isArray(paths)) return { paths: {} };
+  const pathObject = getPathObject(paths);
+  return {
+    ...swaggerObject,
+    paths: pathObject,
+  };
+};
+
+module.exports = parsePaths;

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

@@ -0,0 +1,80 @@
+const errorMessage = require('../utils/errorMessage');
+const setProperty = require('../utils/setProperty')('parameter');
+const formatDescription = require('../utils/formatDescription');
+const getSchema = require('./schema');
+const generator = require('../utils/generator');
+
+const REQUIRED = 'required';
+const DEPRECATED = 'deprecated';
+const EXPLODE = 'explode';
+const NOEXPLODE = 'noexplode';
+const BODY_PARAM = 'body';
+const FORM_TYPE = 'form';
+
+const defaultParseParameter = {};
+
+const parameterPayload = (options, schema) => ({
+  name: setProperty(options, 'name', {
+    type: 'string',
+    required: true,
+  }),
+  in: setProperty(options, 'in', {
+    type: 'string',
+    required: true,
+  }),
+  description: setProperty(options, 'description', {
+    type: 'string',
+    defaultValue: '',
+  }),
+  required: setProperty(options, 'required', {
+    type: 'boolean',
+    defaultValue: false,
+  }),
+  deprecated: setProperty(options, 'deprecated', {
+    type: 'boolean',
+    defaultValue: false,
+  }),
+  explode: setProperty(options, 'explode', {
+    type: 'boolean',
+  }),
+  schema,
+});
+
+const wrongInOption = paramValue => {
+  if (!paramValue.includes('request.body')) {
+    errorMessage(`If you want to add one @param as body you must provide "request.body" instead of ${paramValue}`);
+  }
+  return defaultParseParameter;
+};
+
+const parseParameter = param => {
+  const [name, inOption, ...extraOptions] = param.name.split('.');
+  if (!name || !inOption || inOption === FORM_TYPE) {
+    return defaultParseParameter;
+  }
+  if (inOption === BODY_PARAM) {
+    return wrongInOption(param.name);
+  }
+  const isRequired = extraOptions.includes(REQUIRED);
+  const isDeprecated = extraOptions.includes(DEPRECATED);
+  const shouldExplode = extraOptions.includes(EXPLODE);
+  const shouldNotExplode = extraOptions.includes(NOEXPLODE);
+  const [description, enumValues, jsonOptions] = formatDescription(param.description);
+  const options = {
+    name,
+    in: inOption,
+    required: isRequired,
+    deprecated: isDeprecated,
+    description,
+  };
+  // Used this format because default when undefined is different depending on if it is a query/form or not
+  if (shouldExplode) {
+    options.explode = true;
+  } else if (shouldNotExplode) {
+    options.explode = false;
+  }
+  const schema = getSchema('@param', param.name)(param.type, enumValues, jsonOptions);
+  return parameterPayload(options, schema);
+};
+
+module.exports = generator(parseParameter, 'name');

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

@@ -0,0 +1,65 @@
+const setProperty = require('../utils/setProperty')('parameter');
+const getContent = require('./content')('@paramBody');
+const mapDescription = require('../utils/mapDescription');
+const formParams = require('./formParams');
+const formatExampleValues = require('../utils/formatExamples')('requestBody');
+
+const REQUIRED = 'required';
+const FORM_TYPE = 'form';
+
+const formatExamples = (exampleValues = []) => exampleValues
+  .reduce((exampleMap, example, i) => ({
+    ...exampleMap,
+    [`example${i + 1}`]: {
+      summary: example.summary,
+      value: example.value,
+    },
+  }), {});
+
+const checkExamples = examples => {
+  const isExample = Array.isArray(examples) && examples.length > 0;
+  return isExample ? formatExamples(examples) : undefined;
+};
+
+const parseBodyParameter = (currentState, body, examples) => {
+  const [name, ...extraOptions] = body.name.split('.');
+  const isRequired = extraOptions.includes(REQUIRED);
+  const hasForm = extraOptions.includes(FORM_TYPE);
+  const [description, contentType] = mapDescription(body.description);
+  const options = { name, required: isRequired, description };
+
+  const examplesParsed = examples.map(example => (
+    formatExampleValues(example, contentType)
+  ));
+
+  if (hasForm) {
+    return formParams(currentState, name, body, isRequired, checkExamples(examplesParsed));
+  }
+
+  return {
+    ...currentState,
+    description: setProperty(options, 'description', {
+      type: 'string',
+    }),
+    required: setProperty(options, 'required', {
+      type: 'boolean',
+      defaultValue: false,
+    }),
+    content: {
+      ...currentState.content,
+      ...getContent(body.type, contentType, body.description, checkExamples(examplesParsed)),
+    },
+  };
+};
+
+const INITIAL_STATE = { content: {} };
+
+const requestBodyGenerator = (examples, params = []) => {
+  if (!params || !Array.isArray(params)) return {};
+
+  return params.reduce((acc, body) => (
+    { ...acc, ...parseBodyParameter(acc, body, examples) }
+  ), INITIAL_STATE);
+};
+
+module.exports = requestBodyGenerator;

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

@@ -0,0 +1,55 @@
+const errorMessage = require('../utils/errorMessage');
+const STATUS_CODES = require('./validStatusCodes');
+const mapDescription = require('../utils/mapDescription');
+const getContent = require('./content')('@return');
+const formatExampleValues = require('../utils/formatExamples')('responses');
+
+const DEFAULT_CONTENT_TYPE = 'application/json';
+
+const hasOldContent = (value, status) => (value[status] && value[status].content);
+
+const formatResponses = (values, examples) => values.reduce((acc, value) => {
+  const [status, description, contentType] = mapDescription(value.description);
+  if (!STATUS_CODES[status]) {
+    errorMessage(`Status ${status} is not valid to create a response`);
+    return {};
+  }
+
+  const exampleList = formatExampleValues(
+    examples[status],
+    contentType || DEFAULT_CONTENT_TYPE,
+    status,
+  );
+
+  return {
+    ...acc,
+    [status]: {
+      description,
+      ...(value.type ? {
+        content: {
+          ...(hasOldContent(acc, status) ? { ...acc[status].content } : {}),
+          ...getContent(value.type, contentType, value.description, exampleList),
+        },
+      } : {}),
+    },
+  };
+}, {});
+
+const formatExamples = (exampleValues = []) => exampleValues
+  .reduce((exampleMap, example, i) => ({
+    ...exampleMap,
+    [example.status]: {
+      ...exampleMap[example.status],
+      [`example${i + 1}`]: {
+        summary: example.summary,
+        value: example.value,
+      },
+    },
+  }), {});
+
+const responsesGenerator = (returnValues = [], exampleValues = []) => {
+  if (!returnValues || !Array.isArray(returnValues)) return {};
+  return formatResponses(returnValues, formatExamples(exampleValues));
+};
+
+module.exports = responsesGenerator;

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

@@ -0,0 +1,33 @@
+const errorMessage = require('../utils/errorMessage');
+const combineSchema = require('../utils/combineSchema');
+const addEnumValues = require('../utils/enumValues');
+const { refSchema, formatRefSchema } = require('../utils/refSchema');
+
+const getSchema = (entity, message) => (type, enumValues = [], jsonOptions = {}) => {
+  if (!type) {
+    return errorMessage(`Entity: ${entity} could not be parsed. Value: "${message}" is wrong`);
+  }
+  const nameType = type.name;
+  let schema = {
+    ...refSchema(nameType),
+  };
+
+  schema = {
+    ...schema,
+    ...combineSchema(type.elements),
+    ...addEnumValues(enumValues),
+    ...jsonOptions,
+  };
+  const notPrimitiveType = !nameType;
+  if (notPrimitiveType && !type.elements) {
+    const parseItems = formatRefSchema(type.applications);
+    schema = {
+      ...schema,
+      type: type.expression.name.toLowerCase(),
+      items: parseItems.items ? parseItems.items : parseItems,
+    };
+  }
+  return schema;
+};
+
+module.exports = getSchema;

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

@@ -0,0 +1,31 @@
+const { flatArray } = require('../utils/arrays');
+
+const AND_SEPARATOR = ' & ';
+const OR_SEPARATOR = ' | ';
+
+const formatOrValues = ({ description }) => {
+  if (!description) { return []; }
+
+  const securityNames = description.split(OR_SEPARATOR);
+  return securityNames.map(names => ({
+    description: names,
+  }));
+};
+
+const formatSecurity = (securityValues = []) => (
+  flatArray(securityValues
+    .map(formatOrValues))
+    .map(({ description }) => {
+      const securityNames = description.split(AND_SEPARATOR);
+      return {
+        ...securityNames.reduce((acum, names) => (
+          {
+            ...acum,
+            [names]: [],
+          }
+        ), {}),
+      };
+    })
+);
+
+module.exports = formatSecurity;

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

@@ -0,0 +1,64 @@
+const STATUS_CODES = {
+  202: 'Accepted',
+  502: 'Bad Gateway',
+  400: 'Bad Request',
+  409: 'Conflict',
+  100: 'Continue',
+  201: 'Created',
+  417: 'Expectation Failed',
+  424: 'Failed Dependency',
+  403: 'Forbidden',
+  504: 'Gateway Timeout',
+  410: 'Gone',
+  505: 'HTTP Version Not Supported',
+  418: 'I\'m a teapot',
+  419: 'Insufficient Space on Resource',
+  507: 'Insufficient Storage',
+  500: 'Server Error',
+  411: 'Length Required',
+  423: 'Locked',
+  420: 'Method Failure',
+  405: 'Method Not Allowed',
+  301: 'Moved Permanently',
+  302: 'Moved Temporarily',
+  207: 'Multi-Status',
+  300: 'Multiple Choices',
+  511: 'Network Authentication Required',
+  204: 'No Content',
+  203: 'Non Authoritative Information',
+  406: 'Not Acceptable',
+  404: 'Not Found',
+  501: 'Not Implemented',
+  304: 'Not Modified',
+  200: 'OK',
+  206: 'Partial Content',
+  402: 'Payment Required',
+  308: 'Permanent Redirect',
+  412: 'Precondition Failed',
+  428: 'Precondition Required',
+  102: 'Processing',
+  407: 'Proxy Authentication Required',
+  431: 'Request Header Fields Too Large',
+  408: 'Request Timeout',
+  413: 'Request Entity Too Large',
+  414: 'Request-URI Too Long',
+  416: 'Requested Range Not Satisfiable',
+  205: 'Reset Content',
+  303: 'See Other',
+  503: 'Service Unavailable',
+  101: 'Switching Protocols',
+  307: 'Temporary Redirect',
+  429: 'Too Many Requests',
+  401: 'Unauthorized',
+  422: 'Unprocessable Entity',
+  415: 'Unsupported Media Type',
+  305: 'Use Proxy',
+  '1XX': '1XX Range',
+  '2XX': '2XX Range',
+  '3XX': '3XX Range',
+  '4XX': '4XX Range',
+  '5XX': '5XX Range',
+  default: 'Default response',
+};
+
+module.exports = STATUS_CODES;

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

@@ -0,0 +1,18 @@
+const formatSecurity = securitySchemes => {
+  const securityTypes = Object.keys(securitySchemes);
+  return securityTypes.map(type => ({ [type]: [] }));
+};
+
+const parseSecuritySchemas = (swaggerObject = {}) => {
+  const { security } = swaggerObject;
+  return {
+    ...swaggerObject,
+    ...(security ? { security: formatSecurity(security) } : {}),
+    components: {
+      ...swaggerObject.components,
+      ...(security ? { securitySchemes: security } : {}),
+    },
+  };
+};
+
+module.exports = parseSecuritySchemas;

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

@@ -0,0 +1,41 @@
+const { getTagsInfo, formatDescriptionTag } = require('../utils/tags');
+const { flatArray, getIndexBy } = require('../utils/arrays');
+
+const FILTER_TAG_KEY = 'name';
+
+const formatTags = ({ tags = [] }) => {
+  const infoTags = getTagsInfo(tags, 'tags');
+  return infoTags.map(({ description: tagDescription }) => {
+    const { name, description = '' } = formatDescriptionTag(tagDescription);
+    return {
+      name,
+      description,
+    };
+  });
+};
+
+const sortByDescription = tags => [...tags].sort((a, b) => {
+  if (!a.description && b.description) {
+    return 1;
+  }
+  return -1;
+});
+
+const sortTagsByName = tags => [...tags].sort((a, b) => ((a.name > b.name) ? 1 : -1));
+
+const filterDuplicateTags = tags => (
+  tags.filter(({ name }, i) => getIndexBy(tags, FILTER_TAG_KEY, name) === i)
+);
+
+const parseTags = (swaggerObject, data) => {
+  if (!data || !Array.isArray(data)) return { tags: [] };
+  const tags = flatArray(data.map(formatTags));
+  const ordererTags = sortByDescription(tags);
+  const uniqTags = filterDuplicateTags(ordererTags);
+  return {
+    ...swaggerObject,
+    tags: sortTagsByName(uniqTags),
+  };
+};
+
+module.exports = parseTags;

package/node_modules/express-jsdoc-swagger/transforms/utils/arrays.js

@@ -0,0 +1,12 @@
+const flatArray = elements => (
+  elements.reduce((acc, val) => acc.concat(val), [])
+);
+
+const getIndexBy = (elements, key, value) => (
+  elements.findIndex(element => element[key] === value)
+);
+
+module.exports = {
+  flatArray,
+  getIndexBy,
+};

package/node_modules/express-jsdoc-swagger/transforms/utils/combineSchema.js

@@ -0,0 +1,67 @@
+const { refSchema } = require('./refSchema');
+
+const VALID_TYPES = ['oneOf', 'anyOf', 'allOf'];
+
+/**
+ *  This method checks the first item of the data type list to validate if
+ * it contains any of the keywords representing the different union types
+ * in Swagger: 'oneOf', 'anyOf' or 'allOf'.
+ *
+ * @param {object[]} elements - List of data types for the property
+ * @returns {string|null} Name of the union type (if any)
+ */
+const getUnionType = elements => {
+  const unionType = elements[0].name;
+
+  if (!VALID_TYPES.includes(unionType)) {
+    return null;
+  }
+
+  return unionType;
+};
+
+/**
+ *  This method receives an array of data types passed down to the
+ * 'property' annotation, for example:
+ *
+ *    > '{oneOf|string|null}'.
+ *
+ *  The aim of this method is to process this array and generate
+ * the schema for the property, including a list of its types.
+ *
+ * @param {object[]} elements - List of data types for the property
+ * @returns Swagger schema for the property
+ */
+const combineSchema = elements => {
+  let schema = {};
+  if (!elements || elements.length === 0) return schema;
+
+  // Check if 'null' is part of the listed types and remove it from the array
+  const nullIndex = elements.findIndex(el => el.type === 'NullLiteral');
+  if (nullIndex > 0) {
+    elements.splice(nullIndex, 1);
+    schema = { nullable: true };
+  }
+
+  const unionType = getUnionType(elements);
+  const types = !unionType ? elements : elements.slice(1);
+
+  // If there are multiple types in the list, wrap them into a union type
+  // ('oneOf' will be used by default if none is specified)
+  if (types.length > 1 || unionType === 'allOf') {
+    schema = {
+      ...schema,
+      [unionType || 'oneOf']: types.map(type => refSchema(type)),
+    };
+  } else {
+    // If there's only a type in the list, don't wrap it in 'oneOf' or 'anyOf' blocks
+    schema = {
+      ...schema,
+      ...refSchema(types[0]),
+    };
+  }
+
+  return schema;
+};
+
+module.exports = combineSchema;

package/node_modules/express-jsdoc-swagger/transforms/utils/enumValues.js

@@ -0,0 +1,6 @@
+const addEnumValues = (values = []) => {
+  if (values.length === 0) return {};
+  return { enum: values };
+};
+
+module.exports = addEnumValues;

package/node_modules/express-jsdoc-swagger/transforms/utils/errorMessage.js

@@ -0,0 +1,8 @@
+const chalk = require('chalk');
+
+const errorMessage = message => {
+  // eslint-disable-next-line
+  console.warn(chalk.yellow(`[express-jsdoc-swagger] ${message}`));
+};
+
+module.exports = errorMessage;

package/node_modules/express-jsdoc-swagger/transforms/utils/formatDescription.js

@@ -0,0 +1,35 @@
+const mapDescription = require('./mapDescription');
+const errorMessage = require('./errorMessage');
+
+const ENUM_IDENTIFIER = 'enum:';
+const JSON_IDENTIFIER = 'json:';
+const DESCRIPTION_DIVIDER = ' - ';
+
+const formatDescription = description => {
+  const descriptionTypes = mapDescription(description);
+  const descriptionValue = descriptionTypes.filter(value => (
+    !value.includes(ENUM_IDENTIFIER) && !value.includes(JSON_IDENTIFIER)
+  )).join(DESCRIPTION_DIVIDER);
+  const enumOption = descriptionTypes.find(value => value.includes(ENUM_IDENTIFIER));
+  const jsonOption = descriptionTypes.find(value => value.includes(JSON_IDENTIFIER));
+  const res = [descriptionValue];
+  if (enumOption) {
+    const [, enumOptions] = enumOption.split('enum:');
+    const enumValues = enumOptions.split(',');
+    res.push(enumValues);
+  } else {
+    res.push(undefined);
+  }
+  if (jsonOption) {
+    try {
+      const jsonOptions = JSON.parse(jsonOption.slice(JSON_IDENTIFIER.length));
+      if (typeof jsonOptions !== 'object') { throw new Error('options must be object'); }
+      res.push(jsonOptions);
+    } catch (err) {
+      errorMessage(`json options are malformed: ${err.message}`);
+    }
+  }
+  return res;
+};
+
+module.exports = formatDescription;

package/node_modules/express-jsdoc-swagger/transforms/utils/formatExamples.js

@@ -0,0 +1,25 @@
+const errorMessage = require('./errorMessage');
+
+const DEFAULT_CONTENT_TYPE = 'application/json';
+
+const formatJSONExamples = type => (exampleList, contentType, status) => {
+  let cloneExamples = type === 'requestBody' ? { ...exampleList } : undefined;
+  if (exampleList && contentType === DEFAULT_CONTENT_TYPE) {
+    cloneExamples = { ...exampleList };
+    Object.keys(cloneExamples)
+      .filter(k => typeof cloneExamples[k].value === 'string')
+      .forEach(k => {
+        try {
+          cloneExamples[k].value = JSON.parse(cloneExamples[k].value);
+        } catch (err) {
+          const message = type === 'requestBody'
+            ? 'requestBody example malformed'
+            : `response example for status ${status} with content-type ${DEFAULT_CONTENT_TYPE} malformed`;
+          errorMessage(message);
+        }
+      });
+  }
+  return cloneExamples;
+};
+
+module.exports = formatJSONExamples;

package/node_modules/express-jsdoc-swagger/transforms/utils/generator.js

@@ -0,0 +1,6 @@
+const generator = (parseParameter, filterKey) => paramValues => {
+  if (!paramValues || !Array.isArray(paramValues)) return [];
+  return paramValues.map(parseParameter).filter(param => param[filterKey]);
+};
+
+module.exports = generator;