@tsed/schema 8.0.1 → 8.0.3

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

@@ -0,0 +1,105 @@
+import {getJsonSchema, getSpec, OperationPath, Path, Returns, SpecTypes} from "../../index.js";
+import {WriteOnly} from "./writeOnly.js";
+
+describe("@WriteOnly", () => {
+  it("should declare writeOnly field (with boolean)", () => {
+    // WHEN
+    class Model {
+      @WriteOnly(true)
+      num: string;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      properties: {
+        num: {
+          writeOnly: true,
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare writeOnly field (default value)", () => {
+    // WHEN
+    class Model {
+      @WriteOnly()
+      num: string;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      properties: {
+        num: {
+          writeOnly: true,
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should return the spec (OS3)", () => {
+    // WHEN
+    class Model {
+      @WriteOnly(true)
+      num: string;
+    }
+
+    @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: "string",
+                writeOnly: true
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/Model"
+                    }
+                  }
+                },
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/writeOnly.ts

@@ -0,0 +1,17 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+/**
+ * Set the property as WriteOnly.
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @property
+ * @parameter
+ * @schema
+ */
+export function WriteOnly(writeOnly: boolean = true) {
+  return JsonEntityFn((store: JsonEntityStore) => {
+    store.itemSchema.writeOnly(writeOnly);
+  });
+}

package/src/decorators/config/jsonEntityComponent.ts

@@ -0,0 +1,16 @@
+import {DecoratorTypes, Type} from "@tsed/core";
+
+import {JsonEntitiesContainer, JsonEntityStore} from "../../domain/JsonEntityStore.js";
+
+/**
+ * Declare a new JsonEntityStore class for a specific decorator type.
+ *
+ * @ignore
+ * @param type
+ * @decorator
+ */
+export function JsonEntityComponent(type: DecoratorTypes) {
+  return (target: Type<JsonEntityStore>) => {
+    JsonEntitiesContainer.set(type, target);
+  };
+}

package/src/decorators/generics/genericOf.spec.ts

@@ -0,0 +1,246 @@
+import {CollectionOf, getJsonSchema, Property, string} from "../../index.js";
+import {GenericOf} from "./genericOf.js";
+import {Generics} from "./generics.js";
+
+describe("@GenericOf", () => {
+  it("should generate Generic pagination with nested model (array)", () => {
+    @Generics("T")
+    class Paginated<T> {
+      @CollectionOf("T")
+      data: T[];
+
+      @Property()
+      totalCount: number;
+    }
+
+    class Product {
+      @Property()
+      label: string;
+    }
+
+    class Content {
+      @GenericOf(Product)
+      submissions: Paginated<Product>;
+    }
+
+    expect(getJsonSchema(Content)).toEqual({
+      definitions: {
+        Product: {
+          properties: {
+            label: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      properties: {
+        submissions: {
+          properties: {
+            data: {
+              items: {
+                $ref: "#/definitions/Product"
+              },
+              type: "array"
+            },
+            totalCount: {
+              type: "number"
+            }
+          },
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should generate Generic pagination with nested model", () => {
+    @Generics("T")
+    class Submission<T> {
+      @Property()
+      _id: string;
+
+      @Property("T")
+      data: T;
+    }
+
+    class Product {
+      @Property()
+      label: string;
+    }
+
+    class Content {
+      @GenericOf(Product)
+      submission: Submission<Product>;
+    }
+
+    expect(getJsonSchema(Content)).toEqual({
+      definitions: {
+        Product: {
+          properties: {
+            label: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      properties: {
+        submission: {
+          properties: {
+            _id: {
+              type: "string"
+            },
+            data: {
+              $ref: "#/definitions/Product"
+            }
+          },
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should generate Generic pagination with nested model (deep generics)", () => {
+    @Generics("T")
+    class Paginated<T> {
+      @CollectionOf("T")
+      data: T[];
+
+      @Property()
+      totalCount: number;
+    }
+
+    @Generics("S")
+    class Submission<S> {
+      @Property()
+      _id: string;
+
+      @Property("S")
+      data: S;
+    }
+
+    class Product {
+      @Property()
+      label: string;
+    }
+
+    class Content {
+      @(GenericOf(Submission).Nested(Product))
+      submissions: Paginated<Submission<Product>>;
+    }
+
+    expect(getJsonSchema(Content)).toEqual({
+      definitions: {
+        Product: {
+          properties: {
+            label: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      properties: {
+        submissions: {
+          properties: {
+            data: {
+              items: {
+                properties: {
+                  _id: {
+                    type: "string"
+                  },
+                  data: {
+                    $ref: "#/definitions/Product"
+                  }
+                },
+                type: "object"
+              },
+              type: "array"
+            },
+            totalCount: {
+              type: "number"
+            }
+          },
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should generate Generic with an enum", () => {
+    @Generics("T")
+    class Submission<T> {
+      @Property()
+      _id: string;
+
+      @Property("T")
+      data: T;
+    }
+
+    enum MyEnum {
+      READ = "read",
+      WRITE = "write"
+    }
+
+    class Content {
+      @GenericOf(MyEnum)
+      submission: Submission<MyEnum>;
+    }
+
+    expect(getJsonSchema(Content)).toEqual({
+      properties: {
+        submission: {
+          properties: {
+            _id: {
+              type: "string"
+            },
+            data: {
+              type: "string",
+              enum: ["read", "write"]
+            }
+          },
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should generate Generic with raw json schema", () => {
+    @Generics("T")
+    class Submission<T> {
+      @Property()
+      _id: string;
+
+      @Property("T")
+      data: T;
+    }
+
+    enum MyEnum {
+      READ = "read",
+      WRITE = "write"
+    }
+
+    class Content {
+      @GenericOf(string().enum(["read", "write"]))
+      submission: Submission<MyEnum>;
+    }
+
+    expect(getJsonSchema(Content)).toEqual({
+      properties: {
+        submission: {
+          properties: {
+            _id: {
+              type: "string"
+            },
+            data: {
+              type: "string",
+              enum: ["read", "write"]
+            }
+          },
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/generics/genericOf.ts

@@ -0,0 +1,112 @@
+import {isObject, Type} from "@tsed/core";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {string} from "../../utils/from.js";
+import {GenericValue} from "../../utils/generics.js";
+
+/**
+ * @ignore
+ */
+function isEnum(type: any) {
+  return isObject(type) && !("toJSON" in type);
+}
+
+export interface GenericOfChainedDecorators {
+  (...args: any): any;
+
+  /**
+   * Declare a nested generic models
+   * @param generics
+   */
+  Nested(...generics: GenericValue[]): this;
+}
+
+/**
+ * Set the types of a Generic class.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Product {
+ *   @Property()
+ *   label: string;
+ * }
+ *
+ * @Generics("T")
+ * class Paginated<T> {
+ *   @CollectionOf("T")
+ *   data: T[];
+ *
+ *   @Property()
+ *   totalCount: number;
+ * }
+ *
+ * class Payload {
+ *    @GenericOf(Product)
+ *    products: Paginated<Product>;
+ * }
+ * ```
+ *
+ * ## Example with nested generics
+ *
+ * ```typescript
+ * class Product {
+ *   @Property()
+ *   label: string;
+ * }
+ *
+ * @Generics("T")
+ * class Paginated<T> {
+ *   @CollectionOf("T")
+ *   data: T[];
+ *
+ *   @Property()
+ *   totalCount: number;
+ * }
+ *
+ * @Generics("D")
+ * class Submission<D> {
+ *   @Property()
+ *   _id: string;
+ *
+ *   @Property("D")
+ *   data: D;
+ * }
+ *
+ * class Payload {
+ *    @GenericOf(Submissions).Nested(Product)
+ *    submissions: Paginated<Submission<Product>>;
+ * }
+ * ```
+ *
+ * @param {Type<any>[]} generics
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @generics
+ */
+export function GenericOf(...generics: GenericValue[]): GenericOfChainedDecorators {
+  const nestedGenerics: GenericValue[][] = [
+    generics.map((type) => {
+      if (isEnum(type)) {
+        return string().enum(Object.values(type));
+      }
+      return type;
+    })
+  ];
+
+  const decorator = (...args: any) => {
+    const store = JsonEntityStore.from(...args);
+    store.nestedGenerics = nestedGenerics;
+  };
+
+  decorator.Nested = (...generics: any) => {
+    nestedGenerics.push(generics);
+
+    return decorator;
+  };
+
+  return decorator;
+}

package/src/decorators/generics/generics.ts

@@ -0,0 +1,22 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+
+/**
+ * Define generics list. This list is used by @@GenericOf@@ and the @@getJsonSchema@@ function to build the correct JsonSchema.
+ *
+ * See @@GenericOf@@ decorator for more details.
+ *
+ * @param generics
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @generics
+ */
+export function Generics(...generics: string[]) {
+  return (target: any) => {
+    const storedSchema = JsonEntityStore.from(target);
+
+    storedSchema.schema.genericLabels = generics;
+  };
+}

package/src/decorators/operations/acceptMime.spec.ts

@@ -0,0 +1,39 @@
+import {Get, getSpec, JsonMethodStore, SpecTypes} from "../../index.js";
+import {AcceptMime} from "./acceptMime.js";
+
+describe("AcceptMime", () => {
+  it("should set metadata", () => {
+    class Test {
+      @Get("/")
+      @AcceptMime("application/json")
+      test() {}
+    }
+
+    const endpoint = JsonMethodStore.get(Test, "test");
+    expect(endpoint.acceptMimes).toEqual(["application/json"]);
+
+    const spec = getSpec(Test, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "testTest",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["Test"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Test"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/operations/acceptMime.ts

@@ -0,0 +1,25 @@
+import {StoreSet, useDecorators} from "@tsed/core";
+
+import {Produces} from "./produces.js";
+
+/**
+ * Set a mime list which are acceptable and checks if the specified content types are acceptable, based on the request’s Accept HTTP header field.
+ *
+ * ```typescript
+ *  @Controller('/mypath')
+ *  export class MyCtrl {
+ *
+ *    @Get('/')
+ *    @AcceptMime('application/json')
+ *    public getResource(){}
+ *  }
+ * ```
+ *
+ * @param mimes
+ * @decorator
+ * @operation
+ * @response
+ */
+export function AcceptMime(...mimes: string[]): Function {
+  return useDecorators(Produces(...mimes), StoreSet("acceptMimes", mimes));
+}

package/src/decorators/operations/consumes.spec.ts

@@ -0,0 +1,89 @@
+import {Consumes, getSpec, OperationPath, SpecTypes} from "../../index.js";
+
+describe("Consumes", () => {
+  it("should store metadata", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Consumes("text/json")
+      get() {}
+    }
+
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (class)", () => {
+    @Consumes("text/json")
+    class MyController {
+      @OperationPath("GET", "/")
+      get() {}
+
+      @OperationPath("POST", "/")
+      post() {}
+    }
+
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          },
+          post: {
+            operationId: "myControllerPost",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    class Test {
+      test() {}
+    }
+
+    let actualError: any;
+    try {
+      Consumes("text/json")(Test.prototype, "test", 0);
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("Consumes cannot be used as parameter decorator on Test.test.[0]");
+  });
+});

package/src/decorators/operations/consumes.ts

@@ -0,0 +1,37 @@
+import {decorateMethodsOf, DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Add consumes metadata on the decorated element.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * class Model {
+ *    @Consumes("application/x-www-form-urlencoded")
+ *    id: string;
+ * }
+ * ```
+ *
+ * @param consumes
+ * @decorator
+ * @swagger
+ * @classDecorator
+ * @operation
+ */
+export function Consumes(...consumes: string[]) {
+  return JsonEntityFn((store, args) => {
+    switch (store.decoratorType) {
+      case DecoratorTypes.METHOD:
+        store.operation!.consumes(consumes);
+        break;
+      case DecoratorTypes.CLASS:
+        decorateMethodsOf(args[0], Consumes(...consumes));
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(Consumes, args);
+    }
+  });
+}