@tsed/schema 8.0.1 → 8.0.2

package/src/components/open-spec/operationInQueryMapper.ts

@@ -0,0 +1,74 @@
+import {cleanObject} from "@tsed/core";
+import {OS3Example} from "@tsed/openspec";
+
+import {JsonSchemaOptions} from "../../interfaces/JsonSchemaOptions.js";
+import {registerJsonSchemaMapper} from "../../registries/JsonSchemaMapperContainer.js";
+import {createRefName} from "../../utils/ref.js";
+import type {JsonParameterOptions} from "./operationInParameterMapper.js";
+
+function buildExamples(property: string, examples?: Record<string, OS3Example>) {
+  if (!examples) {
+    return undefined;
+  }
+
+  let hasKey = false;
+
+  const newExamples = Object.entries(examples).reduce((acc, [key, {value, description, ...props}]) => {
+    if (value[property] === undefined) {
+      return acc;
+    }
+
+    hasKey = true;
+
+    return {
+      ...acc,
+      [key]: {
+        ...props,
+        value: value[property],
+        description
+      }
+    };
+  }, {});
+
+  return hasKey ? newExamples : undefined;
+}
+
+function inlineReference(parameter: any, {jsonParameter, ...options}: JsonSchemaOptions) {
+  const name = createRefName(jsonParameter.$schema.getName(), options);
+  const schema = options.components?.schemas?.[name];
+
+  if (schema && !options.oldSchemas?.[name]) {
+    delete options.components!.schemas![jsonParameter.$schema.getName()];
+  }
+
+  return Object.entries(schema?.properties || {}).reduce((params, [key, {description, ...prop}]: [string, any]) => {
+    return [
+      ...params,
+      cleanObject({
+        ...parameter,
+        name: key,
+        required: (schema?.required || []).includes(key),
+        description,
+        schema: prop,
+        style: prop.$ref ? "deepObject" : undefined,
+        examples: buildExamples(key, parameter.examples)
+      })
+    ];
+  }, []);
+}
+
+export function operationInQueryMapper(parameter: any, {jsonSchema, jsonParameters, ...options}: JsonParameterOptions) {
+  if (jsonSchema.$ref) {
+    if (!parameter.name) {
+      return inlineReference(parameter, options);
+    }
+
+    parameter.style = "deepObject";
+  }
+
+  parameter.schema = jsonSchema;
+
+  return parameter;
+}
+
+registerJsonSchemaMapper("operationInQuery", operationInQueryMapper);

package/src/components/open-spec/operationMapper.ts

@@ -0,0 +1,65 @@
+import {getStatusMessage} from "../../constants/httpStatusMessages.js";
+import {JsonOperation} from "../../domain/JsonOperation.js";
+import {JsonParameter} from "../../domain/JsonParameter.js";
+import {isParameterType, JsonParameterTypes} from "../../domain/JsonParameterTypes.js";
+import {JsonSchemaOptions} from "../../interfaces/JsonSchemaOptions.js";
+import {execMapper, registerJsonSchemaMapper} from "../../registries/JsonSchemaMapperContainer.js";
+
+function extractParameters(jsonOperation: JsonOperation, options: JsonSchemaOptions) {
+  return jsonOperation
+    .get("parameters")
+    .filter((parameter: JsonParameter) => isParameterType(parameter.get("in")))
+    .reduce(
+      (inputs: [any[], JsonParameter[]], parameter: JsonParameter) => {
+        const [parameters, bodyParameters] = inputs;
+
+        if ([JsonParameterTypes.BODY, JsonParameterTypes.FILES].includes(parameter.get("in"))) {
+          return [parameters, [...bodyParameters, parameter]];
+        }
+
+        return [[...parameters, parameter], bodyParameters];
+      },
+      [[], []]
+    );
+}
+
+export function operationMapper(jsonOperation: JsonOperation, {tags = [], defaultTags = [], ...options}: JsonSchemaOptions = {}) {
+  const {consumes, produces, ...operation} = execMapper("map", [jsonOperation], {...options, ignore: ["parameters"]});
+
+  if (operation.security) {
+    operation.security = [].concat(operation.security);
+  }
+
+  if (jsonOperation.get("responses").size === 0) {
+    operation.responses = {
+      "200": {
+        description: getStatusMessage(200)
+      }
+    };
+  }
+
+  const parametersOptions = {
+    ...options,
+    consumes: jsonOperation.get("consumes")?.length ? jsonOperation.get("consumes") : ["application/json"]
+  };
+
+  const [parameters, bodyParameters] = extractParameters(jsonOperation, parametersOptions);
+
+  operation.parameters = execMapper("operationInParameters", [parameters], options);
+
+  if (bodyParameters.length) {
+    operation.requestBody = execMapper("operationRequestBody", [bodyParameters], parametersOptions);
+  }
+
+  const operationTags = operation.tags?.length ? operation.tags : defaultTags;
+
+  if (operationTags.length) {
+    operation.tags = operationTags.map(({name}: any) => name);
+  }
+
+  tags.push(...operationTags);
+
+  return operation;
+}
+
+registerJsonSchemaMapper("operation", operationMapper);

package/src/components/open-spec/operationMediaMapper.ts

@@ -0,0 +1,11 @@
+import {JsonMedia} from "../../domain/JsonMedia.js";
+import {JsonSchemaOptions} from "../../interfaces/JsonSchemaOptions.js";
+import {execMapper, registerJsonSchemaMapper} from "../../registries/JsonSchemaMapperContainer.js";
+
+export function operationMediaMapper(jsonMedia: JsonMedia, options: JsonSchemaOptions) {
+  let groups = [...(jsonMedia.groups || [])];
+
+  return execMapper("map", [jsonMedia], {...options, groups, groupsName: jsonMedia.groupsName});
+}
+
+registerJsonSchemaMapper("operationMedia", operationMediaMapper);

package/src/components/open-spec/operationRequestBodyMapper.ts

@@ -0,0 +1,82 @@
+import {JsonParameter} from "../../domain/JsonParameter.js";
+import {JsonRequestBody} from "../../domain/JsonRequestBody.js";
+import {JsonSchema} from "../../domain/JsonSchema.js";
+import {JsonSchemaOptions} from "../../interfaces/JsonSchemaOptions.js";
+import {execMapper, registerJsonSchemaMapper} from "../../registries/JsonSchemaMapperContainer.js";
+
+function buildSchemaFromBodyParameters(parameters: JsonParameter[], options: JsonSchemaOptions) {
+  let schema = new JsonSchema();
+  const props: any = {};
+  const refs: JsonSchema[] = [];
+  let propsLength = 0;
+
+  const hasFile = parameters.some((param) => param.get("in") === "files");
+
+  parameters.forEach((parameter) => {
+    const name = parameter.getName();
+
+    [...parameter.entries()]
+      .filter(([key]) => !["in", "name"].includes(key))
+      .forEach(([key, value]) => {
+        if (props[key] === undefined) {
+          props[key] = value;
+        }
+      });
+
+    const jsonParameter = execMapper("operationInParameter", [parameter], options);
+
+    if (name) {
+      const propSchema = {
+        ...(jsonParameter.schema || {
+          type: jsonParameter.type
+        })
+      };
+
+      if (hasFile && jsonParameter.description) {
+        propSchema.description = jsonParameter.description;
+      }
+
+      schema.addProperty(name, propSchema);
+
+      if (parameter.get("required")) {
+        schema.addRequired(name);
+      }
+
+      propsLength++;
+    } else {
+      refs.push(jsonParameter);
+    }
+  });
+
+  if (!propsLength) {
+    if (refs.length === 1) {
+      return refs[0];
+    }
+  }
+
+  schema.type("object");
+
+  if (props.description && hasFile) {
+    delete props.description;
+  }
+
+  return {
+    schema: schema.toJSON(options),
+    required: false,
+    ...props
+  };
+}
+
+export function operationRequestBodyMapper(bodyParameters: JsonParameter[], {consumes, ...options}: JsonSchemaOptions) {
+  const {schema, examples, in: _, ...props} = buildSchemaFromBodyParameters(bodyParameters, options);
+
+  const requestBody = new JsonRequestBody(props);
+
+  consumes.forEach((consume: string) => {
+    requestBody.addContent(consume, schema, examples);
+  });
+
+  return execMapper("map", [requestBody], options);
+}
+
+registerJsonSchemaMapper("operationRequestBody", operationRequestBodyMapper);

package/src/components/open-spec/operationResponseMapper.ts

@@ -0,0 +1,26 @@
+import {JsonResponse} from "../../domain/JsonResponse.js";
+import {JsonSchemaOptions} from "../../interfaces/JsonSchemaOptions.js";
+import {execMapper, registerJsonSchemaMapper} from "../../registries/JsonSchemaMapperContainer.js";
+
+export function operationResponseMapper(jsonResponse: JsonResponse, options: JsonSchemaOptions = {}) {
+  const response = execMapper("map", [jsonResponse], options);
+
+  if (jsonResponse.status === 204) {
+    delete response.content;
+  }
+
+  if (response.headers) {
+    Object.entries(response.headers).forEach(([key, {type, ...props}]: [string, any]) => {
+      response.headers[key] = {
+        ...props,
+        schema: {
+          type
+        }
+      };
+    });
+  }
+
+  return response;
+}
+
+registerJsonSchemaMapper("operationResponse", operationResponseMapper);

package/src/components/open-spec/pathsMapper.ts

@@ -0,0 +1,132 @@
+import {OS3Operation, OS3Paths} from "@tsed/openspec";
+
+import {OperationVerbs} from "../../constants/OperationVerbs.js";
+import {JsonMethodStore} from "../../domain/JsonMethodStore.js";
+import {JsonMethodPath} from "../../domain/JsonOperation.js";
+import {JsonSchemaOptions} from "../../interfaces/JsonSchemaOptions.js";
+import {execMapper, registerJsonSchemaMapper} from "../../registries/JsonSchemaMapperContainer.js";
+import {buildPath} from "../../utils/buildPath.js";
+import {concatParameters} from "../../utils/concatParameters.js";
+import {getJsonEntityStore} from "../../utils/getJsonEntityStore.js";
+import {getJsonPathParameters} from "../../utils/getJsonPathParameters.js";
+import {getOperationsStores} from "../../utils/getOperationsStores.js";
+import {getOperationId} from "../../utils/operationIdFormatter.js";
+import {removeHiddenOperation} from "../../utils/removeHiddenOperation.js";
+
+const ALLOWED_VERBS = [
+  OperationVerbs.ALL,
+  OperationVerbs.GET,
+  OperationVerbs.POST,
+  OperationVerbs.PUT,
+  OperationVerbs.PATCH,
+  OperationVerbs.HEAD,
+  OperationVerbs.OPTIONS,
+  OperationVerbs.DELETE,
+  OperationVerbs.TRACE
+];
+
+function pushToPath(
+  paths: OS3Paths,
+  {
+    path,
+    method,
+    operation
+  }: {
+    method: string;
+    path: string;
+    operation: OS3Operation;
+  }
+) {
+  return {
+    ...paths,
+    [path]: {
+      ...(paths as any)[path],
+      [method.toLowerCase()]: operation
+    }
+  };
+}
+
+function mapOperationInPathParameters(options: JsonSchemaOptions) {
+  return ({
+    operationPath,
+    operation,
+    operationStore
+  }: {
+    operationPath: JsonMethodPath;
+    operation: OS3Operation;
+    operationStore: JsonMethodStore;
+  }) => {
+    const {path, method} = operationPath;
+
+    return getJsonPathParameters(options.ctrlRootPath, path).map(({path, parameters}) => {
+      path = path ? path : "/";
+
+      parameters = concatParameters(
+        parameters.map(({type, ...param}) => {
+          return {
+            ...param,
+            schema: {
+              type
+            }
+          };
+        }),
+        operation
+      );
+
+      return {
+        operation: {
+          ...operation,
+          parameters,
+          operationId:
+            operation.operationId ||
+            getOperationId(path, {
+              ...options,
+              store: operationStore
+            })
+        },
+        method,
+        path
+      };
+    });
+  };
+}
+
+function mapOperation(options: JsonSchemaOptions) {
+  return (operationStore: JsonMethodStore) => {
+    const operationPaths = operationStore.operation.getAllowedOperationPath(ALLOWED_VERBS);
+
+    if (operationPaths.length === 0) {
+      return [];
+    }
+
+    const operation = execMapper("operation", [operationStore.operation], options);
+
+    return operationPaths.map((operationPath) => {
+      return {
+        operationPath,
+        operation,
+        operationStore
+      };
+    });
+  };
+}
+
+export function pathsMapper(model: any, {paths, rootPath, ...options}: JsonSchemaOptions) {
+  const store = getJsonEntityStore(model);
+  const ctrlPath = store.path;
+  const ctrlRootPath = buildPath(rootPath + ctrlPath);
+
+  options = {
+    ...options,
+    ctrlRootPath
+  };
+
+  return [...getOperationsStores(model).values()]
+    .filter(removeHiddenOperation)
+    .filter((operationStore) => operationStore.operation.getAllowedOperationPath(ALLOWED_VERBS).length > 0)
+    .flatMap(mapOperation(options))
+    .flatMap(mapOperationInPathParameters(options))
+    .reduce(pushToPath, paths);
+}
+
+registerJsonSchemaMapper("paths", pathsMapper);

package/src/constants/OperationVerbs.ts

@@ -0,0 +1,29 @@
+export enum OperationVerbs {
+  ALL = "ALL", // special key
+  GET = "GET",
+  POST = "POST",
+  PUT = "PUT",
+  PATCH = "PATCH",
+  HEAD = "HEAD",
+  DELETE = "DELETE",
+  OPTIONS = "OPTIONS",
+  TRACE = "TRACE",
+  PUBLISH = "PUBLISH",
+  SUBSCRIBE = "SUBSCRIBE",
+  CUSTOM = "CUSTOM"
+}
+
+export const OPERATION_HTTP_VERBS = [
+  OperationVerbs.ALL,
+  OperationVerbs.GET,
+  OperationVerbs.POST,
+  OperationVerbs.PUT,
+  OperationVerbs.PATCH,
+  OperationVerbs.HEAD,
+  OperationVerbs.DELETE,
+  OperationVerbs.OPTIONS,
+  OperationVerbs.TRACE,
+  OperationVerbs.CUSTOM
+];
+
+export const OPERATION_WS_VERBS = [OperationVerbs.PUBLISH, OperationVerbs.SUBSCRIBE];

package/src/constants/httpStatusMessages.ts

@@ -0,0 +1,21 @@
+import {constantCase} from "change-case";
+import statuses from "statuses";
+
+export const HTTP_STATUS_MESSAGES = statuses.codes.reduce((map: Record<string, {label: string; code: string}>, code: number) => {
+  const message: string = String(statuses(code));
+  return {
+    ...map,
+    [String(code)]: {label: message, code: constantCase(message)}
+  };
+}, {});
+
+HTTP_STATUS_MESSAGES["200"].label = "Success";
+HTTP_STATUS_MESSAGES["200"].code = "SUCCESS";
+
+export function getStatusConstant(status: number | string) {
+  return (HTTP_STATUS_MESSAGES as any)[status]?.code;
+}
+
+export function getStatusMessage(status: number | string) {
+  return (HTTP_STATUS_MESSAGES as any)[status]?.label;
+}

package/src/constants/jsonSchemaProperties.ts

@@ -0,0 +1,17 @@
+export const MANY_OF_PROPERTIES = ["oneOf", "allOf", "anyOf"];
+export const STRING_PROPERTIES = ["minLength", "maxLength", "pattern", "format"];
+export const BOOLEAN_PROPERTIES = [];
+export const NUMBER_PROPERTIES = ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"];
+export const ARRAY_PROPERTIES = ["maxItems", "minItems", "uniqueItems", "items", "contains", "maxContains", "minContains"];
+export const OBJECT_PROPERTIES = [
+  "maxItems",
+  "minItems",
+  "uniqueItems",
+  "items",
+  "contains",
+  "maxContains",
+  "minContains",
+  "patternProperties",
+  "dependencies"
+];
+export const COMMON_PROPERTIES = ["const", "enum"];

package/src/decorators/class/children.ts

@@ -0,0 +1,22 @@
+import {Store, Type} from "@tsed/core";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Add Children class to compose routes
+ *
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @param children
+ */
+export function Children(...children: Type<any>[]): ClassDecorator {
+  return JsonEntityFn((store) => {
+    store.store.set("childrenControllers", children);
+
+    children.forEach((childToken) => {
+      Store.from(childToken).set("parentController", store.token);
+    });
+  });
+}

package/src/decorators/class/discriminatorValue.ts

@@ -0,0 +1,53 @@
+import {snakeCase} from "change-case";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Declare a Discriminator value on a child class.
+ *
+ * ```ts
+ * export class Event {
+ *   @DiscriminatorKey() // declare this property a discriminator key
+ *   type: string;
+ *
+ *   @Property()
+ *   value: string;
+ * }
+ *
+ * @DiscriminatorValue("page_view")
+ * export class PageView extends Event {
+ *   @Required()
+ *   url: string;
+ * }
+ *
+ * @DiscriminatorValue("action")
+ * export class Action extends Event {
+ *   @Required()
+ *   event: string;
+ * }
+ *
+ * @DiscriminatorValue()
+ * export class CustomAction extends Event {
+ *   @Required()
+ *   event: string;
+ *
+ *   @Property()
+ *   meta: string;
+ * }
+ * ```
+ *
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @param value
+ * @param values
+ */
+export function DiscriminatorValue(value?: string, ...values: string[]): ClassDecorator {
+  return JsonEntityFn((store) => {
+    value = value || snakeCase(store.targetName);
+    if (store.discriminatorAncestor) {
+      store.schema.discriminatorValue(value, ...values);
+    }
+  });
+}

package/src/decorators/collections/collectionContains.ts

@@ -0,0 +1,25 @@
+import {CollectionOf} from "./collectionOf.js";
+
+/**
+ * Set the type of the item collection. The possible value is String, Boolean, Number, Date, Object, Class, etc...
+ *
+ * The array instance will be valid against "contains" if at least one of its elements is valid against the given schema.
+ *
+ * ```typescript
+ * class Model {
+ *    @CollectionContains(String).MinLength(0).MaxLength(0)
+ *    property: string[];
+ * }
+ * ```
+ *
+ * @param {Type<any>} type
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @collections
+ */
+export function CollectionContains(type: any) {
+  return CollectionOf(type).Contains();
+}