@tsed/schema 8.0.0 → 8.0.2

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

@@ -0,0 +1,270 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {AllOf, getJsonSchema, getSpec, In, OneOf, OperationPath, Path, Property, SpecTypes} from "../../index.js";
+import {number, string} from "../../utils/from.js";
+import {AnyOf} from "./anyOf.js";
+
+describe("@AnyOf", () => {
+  it("should declare return schema", () => {
+    // WHEN
+    class Model {
+      @AnyOf(string(), number())
+      num: string;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "number"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare two models", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @AnyOf(One1, One2)
+      test: One1 | One2;
+    }
+
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      definitions: {
+        One1: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            }
+          }
+        },
+        One2: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            }
+          }
+        }
+      },
+      properties: {
+        test: {
+          anyOf: [
+            {
+              $ref: "#/definitions/One1"
+            },
+            {
+              $ref: "#/definitions/One2"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare two models - OS3", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @AnyOf(One1, One2)
+      test: One1 | One2;
+    }
+
+    @Path("/")
+    class MyController {
+      @OperationPath("POST", "/")
+      get(@In("body") payload: Model) {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              test: {
+                anyOf: [
+                  {
+                    $ref: "#/components/schemas/One1"
+                  },
+                  {
+                    $ref: "#/components/schemas/One2"
+                  }
+                ]
+              }
+            },
+            type: "object"
+          },
+          One1: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          },
+          One2: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Model"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should declare two models (array) - OS3", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @AnyOf(One1, One2)
+      list: (One1 | One2)[];
+    }
+
+    @Path("/")
+    class MyController {
+      @OperationPath("POST", "/")
+      get(@In("body") payload: Model) {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              list: {
+                type: "array",
+                items: {
+                  anyOf: [
+                    {
+                      $ref: "#/components/schemas/One1"
+                    },
+                    {
+                      $ref: "#/components/schemas/One2"
+                    }
+                  ]
+                }
+              }
+            },
+            type: "object"
+          },
+          One1: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          },
+          One2: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Model"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/anyOf.ts

@@ -0,0 +1,23 @@
+import {AnyJsonSchema} from "../../domain/JsonSchema.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * See https://tools.ietf.org/html/draft-wright-json-schema-validation-01#section-6.27
+ *
+ * ::: warning
+ * AnyOf isn't supported by OS2
+ * :::
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ * @param anyOf
+ */
+export function AnyOf(...anyOf: AnyJsonSchema[]) {
+  return JsonEntityFn((entity) => {
+    entity.itemSchema.anyOf(anyOf);
+  });
+}

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

@@ -0,0 +1,98 @@
+import {SpecTypes} from "../../domain/SpecTypes.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {getSpec} from "../../utils/getSpec.js";
+import {In} from "../operations/in.js";
+import {OperationPath} from "../operations/operationPath.js";
+import {Path} from "../operations/path.js";
+import {Const} from "./const.js";
+
+describe("@Const", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Const("10")
+      num: string = "10";
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        num: {
+          const: "10",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+
+    expect(getJsonSchema(Model, {specType: SpecTypes.OPENAPI})).toEqual({
+      properties: {
+        num: {
+          type: "string",
+          enum: ["10"]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare prop (spec)", () => {
+    // WHEN
+    class Model {
+      @Const("10")
+      num: string = "10";
+    }
+
+    @Path("/")
+    class MyController {
+      @OperationPath("POST", "/")
+      get(@In("body") payload: Model) {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              num: {
+                type: "string",
+                enum: ["10"]
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Model"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/const.ts

@@ -0,0 +1,68 @@
+import type {JSONSchema6Type} from "json-schema";
+
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * The const keyword is used to restrict a value to a fixed value.
+ *
+ * ::: warning
+ * For v6 user, use @@Const@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ * ### With a string
+ *
+ * ```typescript
+ * class Model {
+ *    @Const("value1")
+ *    property: "value1";
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "string",
+ *       "const": "value1"
+ *     }
+ *   }
+ * }
+ * ```
+ *  * ### With a boolean
+ *
+ * ```typescript
+ * class Model {
+ *    @Const(true)
+ *    property: boolean;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "boolean",
+ *       "const": true
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {string | number | boolean } constValue
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ */
+export function Const(constValue: JSONSchema6Type | any) {
+  return JsonEntityFn((store) => {
+    store.itemSchema.const(constValue);
+  });
+}

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

@@ -0,0 +1,105 @@
+import {CustomKeys, getJsonSchema, getSpec, OperationPath, Path, Returns, SpecTypes} from "../../index.js";
+import {CustomKey} from "./customKey.js";
+
+describe("@CustomKey", () => {
+  it("should declare customKey field", () => {
+    // WHEN
+    class Model {
+      @CustomKey("range", [1, 2])
+      num: number;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model, {customKeys: true});
+
+    expect(schema).toEqual({
+      properties: {
+        num: {
+          type: "number",
+          range: [1, 2]
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should return the spec (OS3)", () => {
+    // WHEN
+    class Model {
+      @CustomKey("range", [1, 2])
+      num: number;
+    }
+
+    @Path("/")
+    class MyController {
+      @OperationPath("GET", "/")
+      @Returns(200, Model)
+      get() {}
+    }
+
+    // THEN
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              num: {
+                type: "number"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/Model"
+                    }
+                  }
+                },
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+
+  it("should declare customKey field (keys)", () => {
+    // WHEN
+    class Model {
+      @CustomKeys({range: [1, 2]})
+      num: number;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model, {customKeys: true});
+
+    expect(schema).toEqual({
+      properties: {
+        num: {
+          type: "number",
+          range: [1, 2]
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/customKey.ts

@@ -0,0 +1,39 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Set a custom key on JsonSchema that is not a part of the official spec.
+ *
+ * This custom key can only be displayed if the @@getJsonSchema@@ is called with `{customKeys: true}`.
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @property
+ * @parameter
+ * @schema
+ */
+export function CustomKey(key: string, value: any) {
+  return JsonEntityFn((store: JsonEntityStore) => {
+    store.itemSchema.customKey(key, value);
+  });
+}
+/**
+ * Set a group of custom keys on JsonSchema that is not a part of the official spec.
+ *
+ * This custom key can only be displayed if the @@getJsonSchema@@ is called with `{customKeys: true}`.
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @property
+ * @parameter
+ * @schema
+ */
+export function CustomKeys(obj: Record<string, any>) {
+  return JsonEntityFn((store: JsonEntityStore) => {
+    Object.entries(obj).forEach(([key, value]) => {
+      store.itemSchema.customKey(key, value);
+    });
+  });
+}

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

@@ -0,0 +1,25 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Default} from "./default.js";
+
+describe("@Default", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Default("10")
+      num: string = "10";
+
+      constructor() {}
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        num: {
+          default: "10",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/default.ts

@@ -0,0 +1,47 @@
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * There are no restrictions placed on the value of this keyword.
+ *
+ * ::: warning
+ * For v6 user, use @@Default@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * This keyword can be used to supply a default JSON value associated with a particular schema.
+ * It is RECOMMENDED that a default value be valid against the associated schema.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Default("10")
+ *    property: string = "10";
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "string",
+ *       "default": "10"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {string | number | boolean | {}} defaultValue
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Default(defaultValue: string | number | boolean | {}) {
+  return JsonEntityFn((store) => {
+    store.itemSchema.default(defaultValue);
+  });
+}

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

@@ -0,0 +1,22 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {DefaultMsg} from "./defaultMsg.js";
+
+describe("@DefaultMsg", () => {
+  it("should declare default message", () => {
+    // WHEN
+    @DefaultMsg("foo should be a string")
+    class Model {
+      property: number;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model, {customKeys: true});
+
+    expect(schema).toEqual({
+      type: "object",
+      errorMessage: {
+        _: "foo should be a string"
+      }
+    });
+  });
+});