@tsed/schema 8.0.0 → 8.0.2

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

@@ -0,0 +1,276 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {SpecTypes} from "../../domain/SpecTypes.js";
+import {number, string} from "../../utils/from.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 {AllOf} from "./allOf.js";
+import {Property} from "./property.js";
+
+describe("@AllOf", () => {
+  it("should declare return schema", () => {
+    // WHEN
+    class Model {
+      @AllOf(string(), number())
+      num: string;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          allOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "number"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare two models", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @AllOf(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: {
+          allOf: [
+            {
+              $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 {
+      @AllOf(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: {
+                allOf: [
+                  {
+                    $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 {
+      @AllOf(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: {
+                  allOf: [
+                    {
+                      $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/allOf.ts

@@ -0,0 +1,19 @@
+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.26
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ * @param allOf
+ */
+export function AllOf(...allOf: AnyJsonSchema[]) {
+  return JsonEntityFn((entity) => {
+    entity.itemSchema.allOf(allOf);
+  });
+}

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

@@ -0,0 +1,130 @@
+import {Ajv} from "ajv";
+
+import {getJsonSchema} from "../../index.js";
+import {Allow} from "./allow.js";
+import {Property} from "./property.js";
+import {Required} from "./required.js";
+
+describe("@Allow", () => {
+  it("should declare required and allow field (without Allow)", () => {
+    // WHEN
+    class Model {
+      @Required()
+      allow: string;
+    }
+
+    // THEN
+    const classSchema = getJsonSchema(Model);
+
+    expect(classSchema).toEqual({
+      properties: {
+        allow: {
+          type: "string",
+          minLength: 1
+        }
+      },
+      required: ["allow"],
+      type: "object"
+    });
+
+    const validate = new Ajv().compile(classSchema);
+    expect(validate({allow: ""})).toBe(false);
+    expect(validate({allow: 0})).toBe(false);
+    expect(validate({})).toBe(false);
+  });
+  it("should declare required and allow field (with Allowed empty string)", () => {
+    // WHEN
+    class Model {
+      @Allow("")
+      allow: string;
+    }
+
+    // THEN
+    const classSchema = getJsonSchema(Model);
+
+    expect(classSchema).toEqual({
+      properties: {
+        allow: {
+          type: "string"
+        }
+      },
+      required: ["allow"],
+      type: "object"
+    });
+
+    const validate = new Ajv().compile(classSchema);
+    expect(validate({allow: ""})).toBe(true);
+    expect(validate({})).toBe(false);
+  });
+  it("should declare required and allow field (with Allowed null basic type)", () => {
+    // WHEN
+    class Model {
+      @Allow(null)
+      allow: string;
+    }
+
+    // THEN
+    const classSchema = getJsonSchema(Model);
+
+    expect(classSchema).toEqual({
+      properties: {
+        allow: {
+          minLength: 1,
+          type: ["null", "string"]
+        }
+      },
+      required: ["allow"],
+      type: "object"
+    });
+
+    const validate = new Ajv().compile(classSchema);
+    expect(validate({allow: null})).toBe(true);
+    expect(validate({})).toBe(false);
+  });
+  it("should declare required and allow field (with Allowed null NestedModel)", () => {
+    // WHEN
+    class NestedModel {
+      @Property()
+      prop: string;
+    }
+
+    class Model {
+      @Allow(null, NestedModel)
+      allow: NestedModel | null;
+    }
+
+    // THEN
+    const spec = getJsonSchema(Model);
+
+    expect(spec).toEqual({
+      definitions: {
+        NestedModel: {
+          properties: {
+            prop: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      properties: {
+        allow: {
+          anyOf: [
+            {
+              type: "null"
+            },
+            {
+              $ref: "#/definitions/NestedModel"
+            }
+          ]
+        }
+      },
+      required: ["allow"],
+      type: "object"
+    });
+
+    const validate = new Ajv().compile(spec);
+    expect(validate({allow: null})).toBe(true);
+    expect(validate({})).toBe(false);
+  });
+});

package/src/decorators/common/allow.ts

@@ -0,0 +1,50 @@
+import {DecoratorTypes, isClass, useDecorators} from "@tsed/core";
+
+import type {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+import {Property} from "./property.js";
+
+/**
+ * Add allowed values when the property or parameters is required.
+ *
+ * #### Example on parameter:
+ *
+ * ```typescript
+ * @Post("/")
+ * async method(@Allow("") @BodyParams("field") field: string) {}
+ * ```
+ * > Required will throw a BadRequest when the given value is `null` or `undefined` but not for an empty string.
+ *
+ * #### Example on model:
+ *
+ * ```typescript
+ * class Model {
+ *   @Allow("")
+ *   field: string;
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Allow(...values: any[]) {
+  const model = values.find((item) => isClass(item));
+  return useDecorators(
+    model && Property(model),
+    JsonEntityFn((store, args) => {
+      if (store.decoratorType === DecoratorTypes.PARAM) {
+        (store as JsonParameterStore).required = true;
+      }
+
+      if (store.decoratorType === DecoratorTypes.PROP) {
+        store.parentSchema.addRequired(store.propertyName);
+      }
+
+      store.schema.allow(...values);
+    })
+  );
+}

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

@@ -0,0 +1,109 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Any} from "./any.js";
+
+describe("@Any", () => {
+  it("should declare any prop", () => {
+    // WHEN
+    class Model {
+      @Any()
+      prop: any;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          anyOf: [
+            {
+              type: "null"
+            },
+            {
+              multipleOf: 1,
+              type: "integer"
+            },
+            {
+              type: "number"
+            },
+            {
+              type: "string"
+            },
+            {
+              type: "boolean"
+            },
+            {
+              type: "array"
+            },
+            {
+              type: "object"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare any prop (uniq type)", () => {
+    // WHEN
+    class Model {
+      @Any(String)
+      prop: any;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare any prop (with list)", () => {
+    // WHEN
+    class Model {
+      @Any(String, Number, Boolean, null)
+      prop: any;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          anyOf: [
+            {
+              type: "null"
+            },
+            {
+              type: "string"
+            },
+            {
+              type: "number"
+            },
+            {
+              type: "boolean"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare any prop (with string, list)", () => {
+    // WHEN
+    class Model {
+      @Any("string", "null")
+      prop: any;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          type: ["null", "string"]
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/any.ts

@@ -0,0 +1,45 @@
+import {Type} from "@tsed/core";
+import type {JSONSchema6TypeName} from "json-schema";
+
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Set the type of the array items.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Any()
+ *    property: any;
+ *
+ *    @Any(String, Number, Boolean)
+ *    property: string | number | boolean;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": ["integer", "number", "string", "boolean", "array", "object", "null"]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Any(...types: (JSONSchema6TypeName | Type<any> | any)[]) {
+  return JsonEntityFn((store) => {
+    store.itemSchema.any(...types);
+  });
+}