@tsed/schema 8.0.1 → 8.0.2

package/src/decorators/common/defaultMsg.ts

@@ -0,0 +1,38 @@
+import {useDecorators} from "@tsed/core";
+
+import {ErrorMsg} from "./errorMsg.js";
+
+/**
+ * Set default error message.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * @DefaultMsg("foo should be a string")
+ * class Model {
+ *    property: number;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": "number"
+ *   }
+ *   "errorMessage": {
+ *     "_": "foo should be a string"
+ *   }
+ * }
+ * ```
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ */
+export function DefaultMsg(message: string): ClassDecorator {
+  return useDecorators(ErrorMsg({_: message}));
+}

package/src/decorators/common/description.spec.ts

@@ -0,0 +1,166 @@
+import {In, OperationPath, Property, SpecTypes} from "../../index.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {getSpec} from "../../utils/getSpec.js";
+import {Description} from "./description.js";
+
+describe("@Description", () => {
+  it("should declare description on class", () => {
+    // WHEN
+    @Description("Description")
+    class Model {}
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      description: "Description",
+      type: "object"
+    });
+  });
+  it("should declare description on method", () => {
+    // WHEN
+
+    class Model {
+      @OperationPath("GET", "/")
+      @Description("Description")
+      method() {}
+    }
+
+    // THEN
+    expect(getSpec(Model)).toEqual({
+      paths: {
+        "/": {
+          get: {
+            description: "Description",
+            operationId: "modelMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["Model"]
+          }
+        }
+      },
+      tags: [{name: "Model"}]
+    });
+  });
+  it("should declare description on property", () => {
+    // WHEN
+
+    class Model {
+      @Description("Description")
+      method: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        method: {
+          description: "Description",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare description on params (QUERY)", () => {
+    // WHEN
+
+    class Model {
+      @OperationPath("GET", "/")
+      method(@In("query") @Description("Description") query: string) {}
+    }
+
+    // THEN
+    expect(getSpec(Model, {specType: SpecTypes.OPENAPI})).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "modelMethod",
+            parameters: [
+              {
+                description: "Description",
+                in: "query",
+                required: false,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["Model"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Model"
+        }
+      ]
+    });
+  });
+  it("should declare description on params (BODY)", () => {
+    // WHEN
+    class MyModel {
+      @Property()
+      id: string;
+    }
+
+    class MyController {
+      @OperationPath("POST", "/")
+      method(@In("body") @Description("Description") payload: MyModel) {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    // THEN
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          MyModel: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerMethod",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/MyModel"
+                  }
+                }
+              },
+              description: "Description",
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+});

package/src/decorators/common/description.ts

@@ -0,0 +1,77 @@
+import {DecoratorParameters, decoratorTypeOf, DecoratorTypes} from "@tsed/core";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import type {JsonMethodStore} from "../../domain/JsonMethodStore.js";
+import type {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Add a description to the class, method or property
+ *
+ * ## Examples
+ * ### On class
+ *
+ * ```typescript
+ * @Description("description")
+ * class Model {
+ *
+ * }
+ * ```
+ *
+ * ### On method
+ *
+ * ```typescript
+ * @Controller("/")
+ * class ModelCtrl {
+ *    @Description("description")
+ *    async method() {}
+ * }
+ * ```
+ *
+ * ### On parameter
+ *
+ * ```typescript
+ * @Controller("/")
+ * class ModelCtrl {
+ *    async method(@Description("description") @PathParam("id") id: string) {}
+ * }
+ * ```
+ *
+ * ### On property
+ *
+ * ```typescript
+ * class Model {
+ *    @Description("description")
+ *    id: string;
+ * }
+ * ```
+ *
+ * @param {string} description
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @classDecorator
+ * @methodDecorator
+ * @propertyDecorator
+ * @parameterDecorator
+ */
+export function Description(description: any) {
+  return JsonEntityFn((store: JsonEntityStore, args: DecoratorParameters) => {
+    switch (decoratorTypeOf(args)) {
+      case DecoratorTypes.PROP:
+      case DecoratorTypes.CLASS:
+        store.schema.description(description);
+        break;
+
+      case DecoratorTypes.PARAM:
+        (store as JsonParameterStore).parameter.description(description);
+        break;
+
+      case DecoratorTypes.METHOD:
+        (store as JsonMethodStore).operation?.description(description);
+        break;
+    }
+  });
+}

package/src/decorators/common/discriminatorKey.ts

@@ -0,0 +1,14 @@
+import {useDecorators} from "@tsed/core";
+
+import {JsonPropertyStore} from "../../domain/JsonPropertyStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+import {Property} from "./property.js";
+
+export function DiscriminatorKey(): PropertyDecorator {
+  return useDecorators(
+    Property(),
+    JsonEntityFn((store: JsonPropertyStore) => {
+      store.discriminatorKey();
+    })
+  );
+}

package/src/decorators/common/enum.spec.ts

@@ -0,0 +1,305 @@
+import {enums} from "../../utils/from.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Enum} from "./enum.js";
+
+describe("@Enum", () => {
+  describe("when enum is a list of values", () => {
+    it("should declare prop (uniq type)", () => {
+      // WHEN
+      class Model {
+        @Enum("0", "1")
+        num: string;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            enum: ["0", "1"],
+            type: "string"
+          }
+        },
+        type: "object"
+      });
+    });
+    it("should declare prop (mixed type)", () => {
+      // WHEN
+      class Model {
+        @Enum("0", "1", 10)
+        num: string | number;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            anyOf: [
+              {
+                enum: ["0", "1"],
+                type: "string"
+              },
+              {
+                enum: [10],
+                type: "number"
+              }
+            ]
+          }
+        },
+        type: "object"
+      });
+    });
+    it("should declare prop (mixed type and null)", () => {
+      // WHEN
+      class Model {
+        @Enum("0", "1", 10, null)
+        num: string | number;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            anyOf: [
+              {
+                type: "null"
+              },
+              {
+                enum: ["0", "1"],
+                type: "string"
+              },
+              {
+                enum: [10],
+                type: "number"
+              }
+            ]
+          }
+        },
+        type: "object"
+      });
+    });
+    it("should declare prop (mixed type, object, and null)", () => {
+      // WHEN
+      class Model {
+        @Enum("0", "1", 10, {test: "test"}, null)
+        num: string | number;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            anyOf: [
+              {
+                type: "null"
+              },
+              {
+                enum: ["0", "1", "test"],
+                type: "string"
+              },
+              {
+                enum: [10],
+                type: "number"
+              }
+            ]
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+
+  describe("when is a typescript enum (string)", () => {
+    it("should declare prop", () => {
+      enum SomeEnum {
+        ENUM_1 = "enum1",
+        ENUM_2 = "enum2"
+      }
+
+      // WHEN
+      class Model {
+        @Enum(SomeEnum)
+        num: SomeEnum;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            enum: ["enum1", "enum2"],
+            type: "string"
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+
+  describe("when is a typescript enum (index)", () => {
+    it("should declare prop", () => {
+      enum SomeEnum {
+        ENUM_1,
+        ENUM_2
+      }
+
+      // WHEN
+      class Model {
+        @Enum(SomeEnum)
+        num: SomeEnum;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            enum: [0, 1],
+            type: "number"
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+
+  describe("when is a typescript enum (mixed type)", () => {
+    it("should declare prop", () => {
+      enum SomeEnum {
+        ENUM_1,
+        ENUM_2 = "test",
+        ENUM_3 = "test2"
+      }
+
+      // WHEN
+      class Model {
+        @Enum(SomeEnum)
+        num: SomeEnum;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            anyOf: [
+              {
+                enum: [0],
+                type: "number"
+              },
+              {
+                enum: ["test", "test2"],
+                type: "string"
+              }
+            ]
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+  describe("when is a typescript enum with a label (set enum schema)", () => {
+    it("should declare prop with a shared enum in definitions", () => {
+      enum SomeEnum {
+        ENUM_1,
+        ENUM_2 = "test",
+        ENUM_3 = "test2"
+      }
+
+      const enumValues = enums(SomeEnum).label("SomeEnum");
+
+      // WHEN
+      class Model {
+        @Enum(enumValues)
+        num: SomeEnum;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        definitions: {
+          SomeEnum: {
+            anyOf: [
+              {
+                enum: [0],
+                type: "number"
+              },
+              {
+                enum: ["test", "test2"],
+                type: "string"
+              }
+            ]
+          }
+        },
+        properties: {
+          num: {
+            $ref: "#/definitions/SomeEnum"
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+  describe("when is a typescript enum with a label (set enum)", () => {
+    it("should declare prop with a shared enum in definitions", () => {
+      enum SomeEnum {
+        ENUM_1,
+        ENUM_2 = "test",
+        ENUM_3 = "test2"
+      }
+
+      enums(SomeEnum).label("SomeEnum");
+
+      // WHEN
+      class Model {
+        @Enum(SomeEnum)
+        num: SomeEnum;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        definitions: {
+          SomeEnum: {
+            anyOf: [
+              {
+                enum: [0],
+                type: "number"
+              },
+              {
+                enum: ["test", "test2"],
+                type: "string"
+              }
+            ]
+          }
+        },
+        properties: {
+          num: {
+            $ref: "#/definitions/SomeEnum"
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+  describe("when is a typescript enum schema without label (set enum)", () => {
+    it("should inline enum", () => {
+      enum SomeEnum {
+        ENUM_1,
+        ENUM_2 = "test",
+        ENUM_3 = "test2"
+      }
+
+      enums(SomeEnum);
+
+      // WHEN
+      class Model {
+        @Enum(SomeEnum)
+        num: SomeEnum;
+      }
+
+      expect(getJsonSchema(Model)).toEqual({
+        properties: {
+          num: {
+            anyOf: [
+              {
+                enum: [0],
+                type: "number"
+              },
+              {
+                enum: ["test", "test2"],
+                type: "string"
+              }
+            ]
+          }
+        },
+        type: "object"
+      });
+    });
+  });
+});

package/src/decorators/common/enum.ts

@@ -0,0 +1,111 @@
+import type {JSONSchema6Type} from "json-schema";
+
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+function EnumFn(...enumValues: (JSONSchema6Type | any)[]): Function;
+function EnumFn(enumValue: JSONSchema6Type | any, ...enumValues: JSONSchema6Type[]) {
+  return JsonEntityFn((store) => {
+    store.itemSchema.enum(enumValue, ...enumValues);
+  });
+}
+
+/**
+ * The enum keyword is used to restrict a value to a fixed set of values.
+ * It must be an array with at least one element, where each element is unique.
+ *
+ * Elements in the array might be of any value, including null.
+ *
+ * ::: warning
+ * For v6 user, use @@Enum@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ * ### With primitive type
+ *
+ * ```typescript
+ * class Model {
+ *    @Enum("value1", "value2")
+ *    property: "value1" | "value2";
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "string",
+ *       "enum": ["value1", "value2"]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With array type
+ *
+ * ```typescript
+ * class Model {
+ *    @Enum("value1", "value2")
+ *    property: ("value1" | "value2")[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "array",
+ *       "items": {
+ *          "type": "string",
+ *          "enum": ["value1", "value2"]
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With Typescript Enum
+ *
+ * ```typescript
+ * enum SomeEnum {
+ *    ENUM_1 = "enum1",
+ *    ENUM_2 = "enum2"
+ * }
+ *
+ * class Model {
+ *    @Enum(SomeEnum)
+ *    property: SomeEnum;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *        "type": "string",
+ *        "enum": ["enum1", "enum2"]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {string | number | boolean | {}} enumValue
+ * @param enumValues
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @ajv-errors
+ */
+
+export const Enum = withErrorMsg("enum", EnumFn);