@tsed/schema 8.0.0 → 8.0.2

package/src/domain/JsonMethodStore.spec.ts

@@ -0,0 +1,301 @@
+import {StoreSet} from "@tsed/core";
+// @ts-ignore
+import {Use, UseAfter, UseBefore} from "@tsed/platform-middlewares";
+
+import {OperationVerbs} from "../constants/OperationVerbs.js";
+import {Property} from "../decorators/common/property.js";
+import {In} from "../decorators/operations/in.js";
+import {Returns} from "../decorators/operations/returns.js";
+import {Get} from "../decorators/operations/route.js";
+import {JsonEntityStore} from "./JsonEntityStore.js";
+import {EndpointMetadata, JsonMethodStore} from "./JsonMethodStore.js";
+import {JsonOperation} from "./JsonOperation.js";
+import {JsonParameter} from "./JsonParameter.js";
+
+describe("JsonMethodStore", () => {
+  describe("endpoint declaration", () => {
+    it("should return an endpoint metadata", () => {
+      // GIVEN
+      const middleware1 = () => {};
+      const middleware2 = () => {};
+      const middleware3 = () => {};
+
+      class Test {
+        @StoreSet("test", "value")
+        @(Get("/").Use(middleware3).UseAfter(middleware1).UseBefore(middleware2))
+        method(): any {}
+      }
+
+      const endpoint = JsonEntityStore.fromMethod(Test, "method");
+
+      // THEN
+      expect(endpoint.beforeMiddlewares).toHaveLength(1);
+      expect(endpoint.middlewares).toHaveLength(1);
+      expect(endpoint.beforeMiddlewares).toHaveLength(1);
+      expect(endpoint.token).toBe(Test);
+      expect(endpoint.store.get("test")).toEqual("value");
+    });
+  });
+  describe("view()", () => {
+    it("should return view value", () => {
+      // GIVEN
+      const middleware3 = () => {};
+
+      class Test {
+        @Use(middleware3)
+        method(): any {}
+      }
+
+      const endpoint = EndpointMetadata.get(Test, "method");
+
+      // @ts-ignore
+      endpoint.view = {path: "/", test: 1};
+
+      expect(endpoint.view).toEqual({path: "/", test: 1});
+    });
+  });
+  describe("acceptMimes()", () => {
+    it("should return acceptMimes value", () => {
+      // GIVEN
+      const middleware3 = () => {};
+
+      class Test {
+        @Use(middleware3)
+        method(): any {}
+      }
+
+      const endpoint = EndpointMetadata.get(Test, "method");
+
+      // @ts-ignore
+      endpoint.acceptMimes = [];
+
+      expect(endpoint.acceptMimes).toEqual([]);
+    });
+  });
+  describe("endpoint declaration (2)", () => {
+    it("should return an endpoint metadata", () => {
+      // GIVEN
+      const middleware1 = () => {};
+      const middleware2 = () => {};
+      const middleware3 = () => {};
+
+      class Test {
+        @UseAfter(middleware1)
+        @UseBefore(middleware2)
+        @Use(middleware3)
+        @StoreSet("test", "value")
+        method(): any {}
+      }
+
+      const endpoint = EndpointMetadata.get(Test, "method");
+
+      // THEN
+      expect(endpoint.beforeMiddlewares).toHaveLength(1);
+      expect(endpoint.middlewares).toHaveLength(1);
+      expect(endpoint.beforeMiddlewares).toHaveLength(1);
+      expect(endpoint.token).toEqual(Test);
+      expect(endpoint.store.get("test")).toEqual("value");
+    });
+    it("should add endpoint with path", () => {
+      // GIVEN
+      const middleware = () => {};
+
+      class Test {
+        @Use("/", middleware)
+        method(): any {}
+      }
+
+      const endpoint = EndpointMetadata.get(Test, "method");
+
+      // THEN
+      expect(endpoint.middlewares).toHaveLength(1);
+    });
+    it("should add endpoint with path and method", () => {
+      // GIVEN
+      const middleware = () => {};
+
+      class Test {
+        @Use("get", "/", middleware)
+        method(): any {}
+      }
+
+      const endpoint = EndpointMetadata.get(Test, "method");
+
+      // THEN
+      expect(endpoint.middlewares).toHaveLength(1);
+
+      expect([...endpoint.operationPaths.values()]).toEqual([
+        {
+          method: OperationVerbs.GET,
+          path: "/"
+        }
+      ]);
+    });
+  });
+  describe("static get()", () => {
+    it("should return the endpoint metadata", () => {
+      const middleware1 = () => {};
+      const middleware2 = () => {};
+      const middleware3 = () => {};
+
+      class Test {
+        @UseAfter(middleware1)
+        @UseBefore(middleware2)
+        @Use(middleware3)
+        @StoreSet("test", "Test")
+        method(): any {}
+
+        @Use(middleware3)
+        @StoreSet("test", "Test")
+        method3() {}
+      }
+
+      const endpoint = JsonMethodStore.get(Test, "method");
+      expect(endpoint).toBeInstanceOf(JsonMethodStore);
+    });
+  });
+  describe("get()", () => {
+    it("should return the endpoint metadata", () => {
+      const middleware1 = () => {};
+      const middleware2 = () => {};
+      const middleware3 = () => {};
+
+      class Test {
+        @UseAfter(middleware1)
+        @UseBefore(middleware2)
+        @Use(middleware3)
+        @StoreSet("test", "Test")
+        method(): any {}
+
+        @Use(middleware3)
+        @StoreSet("test", "Test")
+        method3() {}
+      }
+
+      const endpoint = JsonMethodStore.get(Test, "method");
+      expect(endpoint.get("test")).toEqual("Test");
+    });
+  });
+
+  describe("getResponseOptions()", () => {
+    it("should return the response options (200/201)", () => {
+      class MyController {
+        @Get("/")
+        @Returns(200, Object)
+        method(@In("path") param: string) {}
+      }
+
+      // METHOD
+      const storeMethod = JsonEntityStore.from(MyController).children.get("method");
+
+      expect(storeMethod?.getResponseOptions(200)).toEqual({
+        groups: undefined,
+        type: Object
+      });
+      expect(storeMethod?.getResponseOptions(201)).toEqual({
+        type: Object
+      });
+    });
+    it("should return the response options (200 + includes)", () => {
+      class MyController {
+        @Get("/")
+        @(Returns(200, Object).AllowedGroups("summary"))
+        method(@In("path") param: string) {}
+      }
+
+      // METHOD
+      const storeMethod = JsonEntityStore.from(MyController).children.get("method");
+
+      expect(storeMethod?.getResponseOptions(200, {includes: undefined})).toEqual({
+        groups: undefined,
+        type: Object
+      });
+      expect(storeMethod?.getResponseOptions(200, {includes: []})).toEqual({
+        groups: [],
+        type: Object
+      });
+      expect(storeMethod?.getResponseOptions(200, {includes: ["summary", "admin"]})).toEqual({
+        groups: ["summary"],
+        type: Object
+      });
+    });
+  });
+
+  describe("stores", () => {
+    it("should return all stores", () => {
+      class Model {
+        @Property()
+        id: string;
+
+        @Get("/")
+        @Returns(200, Object)
+        method(@In("path") param: string) {}
+      }
+
+      // CLASS
+      const storeClass = JsonEntityStore.from(Model);
+      expect(storeClass).toBeInstanceOf(JsonEntityStore);
+      expect(storeClass.decoratorType).toBe("class");
+      expect(storeClass.propertyName).toBe("undefined");
+      expect(storeClass.propertyKey).toBeUndefined();
+      expect(storeClass.index).toBeUndefined();
+      expect(storeClass.parent).toBe(storeClass);
+
+      // PROPERTY
+      const storeProp = JsonEntityStore.from(Model).children.get("id");
+      expect(storeProp).toBeInstanceOf(JsonEntityStore);
+      expect(storeProp?.decoratorType).toBe("property");
+      expect(storeProp?.propertyKey).toBe("id");
+      expect(storeProp?.propertyName).toBe("id");
+      expect(storeProp?.index).toBeUndefined();
+      expect(storeProp?.parameter).toBeUndefined();
+      expect(storeProp?.operation).toBeUndefined();
+      expect(storeProp?.nestedGenerics).toEqual([]);
+      expect(storeProp?.parent).toEqual(storeClass);
+
+      // METHOD
+      const storeMethod = JsonEntityStore.from(Model).children.get("method");
+      expect(storeMethod).toBeInstanceOf(JsonEntityStore);
+      expect(storeMethod?.propertyKey).toBe("method");
+      expect(storeMethod?.propertyName).toBe("method");
+      expect(storeMethod?.decoratorType).toBe("method");
+      expect(storeMethod?.index).toBeUndefined();
+      expect(storeMethod?.parameters.length).toEqual(1);
+      expect(storeMethod?.params.length).toEqual(1);
+
+      expect([...storeMethod?.operationPaths.entries()]).toEqual([
+        [
+          "GET/",
+          {
+            method: "GET",
+            path: "/"
+          }
+        ]
+      ]);
+      expect(storeMethod?.getResponseOptions(200)).toEqual({
+        groups: undefined,
+        type: Object
+      });
+      expect(storeMethod?.getResponseOptions(201)).toEqual({
+        type: Object
+      });
+      expect(storeMethod?.operation).toBeInstanceOf(JsonOperation);
+      expect(storeMethod?.nestedGenerics).toEqual([]);
+      expect(storeProp?.parent).toEqual(storeClass);
+
+      // PARAMETERS
+      const storeParam = JsonEntityStore.from(Model).children.get("method")?.children.get(0);
+
+      expect(storeParam).toBeInstanceOf(JsonEntityStore);
+      expect(storeParam?.propertyKey).toBe("method");
+      expect(storeParam?.propertyName).toBe("method");
+      expect(storeParam?.index).toBe(0);
+      expect(storeParam?.decoratorType).toBe("parameter");
+      expect(storeParam?.parameter).toBeInstanceOf(JsonParameter);
+      expect(storeParam?.operation).toBeUndefined();
+      expect(storeParam?.nestedGenerics).toEqual([]);
+      expect(storeParam?.nestedGenerics).toEqual([]);
+      expect(storeParam?.parent).toEqual(storeMethod);
+    });
+  });
+});

package/src/domain/JsonMethodStore.ts

@@ -0,0 +1,212 @@
+import {DecoratorTypes, deepMerge, descriptorOf, isCollection, isFunction, isPromise, Metadata, prototypeOf, Store, Type} from "@tsed/core";
+
+import {JsonEntityComponent} from "../decorators/config/jsonEntityComponent.js";
+import type {JsonClassStore} from "./JsonClassStore.js";
+import {JsonEntityStore, JsonEntityStoreOptions} from "./JsonEntityStore.js";
+import {JsonOperation} from "./JsonOperation.js";
+import type {JsonParameterStore} from "./JsonParameterStore.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+export interface JsonViewOptions {
+  path: string;
+  options: any;
+}
+
+export interface JsonRedirectOptions {
+  status: number | undefined;
+  url: string;
+}
+
+@JsonEntityComponent(DecoratorTypes.METHOD)
+export class JsonMethodStore extends JsonEntityStore {
+  readonly parent: JsonClassStore = JsonEntityStore.from(this.target);
+  public middlewares: any[] = [];
+  public beforeMiddlewares: any[] = [];
+  public afterMiddlewares: any[] = [];
+  /**
+   * Ref to JsonOperation when the decorated object is a method.
+   */
+  readonly operation: JsonOperation = new JsonOperation();
+  /**
+   * List of children JsonEntityStore (properties or methods or params)
+   */
+  readonly children: Map<string | number, JsonParameterStore> = new Map();
+
+  constructor(options: JsonEntityStoreOptions) {
+    super({
+      store: Store.fromMethod(options.target, options.propertyKey!),
+      descriptor: descriptorOf(options.target, options.propertyKey!),
+      ...options
+    });
+
+    const {beforeMiddlewares = [], middlewares = [], afterMiddlewares = []} = options;
+
+    this.after(afterMiddlewares);
+    this.before(beforeMiddlewares);
+    this.use(middlewares);
+  }
+
+  get params(): JsonParameterStore[] {
+    return this.parameters;
+  }
+
+  get view(): JsonViewOptions {
+    return this.store.get("view") as JsonViewOptions;
+  }
+
+  set view(view: JsonViewOptions) {
+    this.store.set("view", view);
+  }
+
+  get acceptMimes(): string[] {
+    return this.store.get<string[]>("acceptMimes", []);
+  }
+
+  set acceptMimes(mimes: string[]) {
+    this.store.set("acceptMimes", mimes);
+  }
+
+  get parameters(): JsonParameterStore[] {
+    return [...this.children.values()] as JsonParameterStore[];
+  }
+
+  get operationPaths() {
+    return this.operation.operationPaths;
+  }
+
+  /**
+   * Get an endpoint.
+   * @param target
+   * @param propertyKey
+   * @param descriptor
+   */
+  static get(target: Type<any>, propertyKey: string | symbol, descriptor?: PropertyDescriptor): JsonMethodStore {
+    descriptor = descriptor || descriptorOf(prototypeOf(target), propertyKey);
+
+    return JsonEntityStore.from<JsonMethodStore>(prototypeOf(target), propertyKey, descriptor);
+  }
+
+  getResponseOptions(
+    status: number,
+    {contentType = "application/json", includes}: {contentType?: string; includes?: string[]} = {}
+  ): undefined | any {
+    const media = this.operation.getResponseOf(status).getMedia(contentType, false);
+
+    if (media && media.has("schema")) {
+      const schema = media.get("schema") as JsonSchema;
+      let groups = media.groups;
+
+      if (includes && media.allowedGroups?.size) {
+        groups = [...(groups || []), ...includes.filter((include) => media.allowedGroups!.has(include))];
+      }
+
+      return {type: schema.getComputedItemType(), groups};
+    }
+
+    return {type: this.type};
+  }
+
+  /**
+   * Append middlewares to the beforeMiddlewares list.
+   * @param args
+   * @returns {EndpointMetadata}
+   */
+  public before(args: Function[]): this {
+    this.beforeMiddlewares = this.beforeMiddlewares.concat(args).filter(isFunction);
+
+    return this;
+  }
+
+  /**
+   * Append middlewares to the afterMiddlewares list.
+   * @param args
+   * @returns {EndpointMetadata}
+   */
+  public after(args: Function[]): this {
+    this.afterMiddlewares = this.afterMiddlewares.concat(args).filter(isFunction);
+
+    return this;
+  }
+
+  /**
+   * Store all arguments collected via Annotation.
+   * @param args
+   */
+  public use(args: Function[]) {
+    this.middlewares = this.middlewares.concat(args).filter(isFunction);
+
+    return this;
+  }
+
+  /**
+   * Find the value at the controller level. Let this value be extended or overridden by the endpoint itself.
+   *
+   * @param key
+   * @returns {any}
+   */
+  public get<T = any>(key: any): T {
+    const ctrlValue = Store.from(this.target).get(key);
+
+    return deepMerge<T>(ctrlValue, this.store.get(key));
+  }
+
+  public getParamTypes(): Record<string, boolean> {
+    return [...this.children.values()].reduce(
+      (obj, item) => ({
+        ...obj,
+        [item.paramType]: true
+      }),
+      {}
+    );
+  }
+
+  protected build() {
+    if (!this._type) {
+      let type: any = Metadata.getReturnType(this.target, this.propertyKey);
+      type = isPromise(type) ? undefined : type;
+
+      this.buildType(type);
+    }
+
+    this._type = this._type || Object;
+
+    this.parent.children.set(this.propertyName, this);
+
+    if (isCollection(this._type)) {
+      this.collectionType = this._type;
+      // @ts-ignore
+      delete this._type;
+    }
+
+    this._schema = JsonSchema.from({
+      type: this.collectionType || this.type
+    });
+
+    if (this.collectionType) {
+      this._schema.itemSchema(this.type);
+    }
+
+    this.parent.schema.addProperty(this.propertyName, this.schema);
+  }
+}
+
+/**
+ * EndpointMetadata contains metadata about a controller and his method.
+ * Each annotation (@Get, @Body...) attached to a method are stored into endpoint.
+ * EndpointMetadata convert this metadata to an array which contain arguments to call an Express method.
+ *
+ * Example :
+ *```typescript
+ * @Controller("/my-path")
+ * provide MyClass {
+ *
+ *     @Get("/")
+ *     @Authenticated()
+ *     public myMethod(){}
+ * }
+ *```
+ *
+ * @alias JsonMethodStore
+ */
+export type EndpointMetadata = JsonMethodStore;
+export const EndpointMetadata = JsonMethodStore;

package/src/domain/JsonOperation.spec.ts

@@ -0,0 +1,126 @@
+import {descriptorOf} from "@tsed/core";
+
+import {execMapper, Get, getSpec, In, JsonEntityStore, OperationPath, Path, Redirect, Returns, SpecTypes} from "../index.js";
+
+describe("JsonOperation", () => {
+  describe("getStatus()", () => {
+    it("should return the status", () => {
+      class MyController {
+        @OperationPath("GET", "/")
+        @(Returns(200).Header("x-token", "token"))
+        @(Returns(200).Header("x-token2", "token2"))
+        method() {}
+      }
+
+      const entity = JsonEntityStore.from(MyController.prototype, "method", descriptorOf(MyController, "method"));
+
+      expect(entity.operation?.getStatus()).toBe(200);
+      expect(entity.operation?.status).toBe(200);
+      expect(execMapper("operationResponse", [entity.operation?.response], {})).toEqual({
+        content: {
+          "*/*": {
+            schema: {
+              type: "object"
+            }
+          }
+        },
+        description: "Success",
+        headers: {
+          "x-token": {
+            example: "token",
+            schema: {
+              type: "string"
+            }
+          },
+          "x-token2": {
+            example: "token2",
+            schema: {
+              type: "string"
+            }
+          }
+        }
+      });
+      expect(entity.operation?.getHeadersOf(200)).toEqual({
+        "x-token": {
+          example: "token",
+          type: "string"
+        },
+        "x-token2": {
+          example: "token2",
+          type: "string"
+        }
+      });
+    });
+  });
+  describe("isRedirection()", () => {
+    it("should return redirection status", () => {
+      @Path("/")
+      class MyController {
+        @Redirect("/path/to")
+        @Get("/")
+        test() {}
+      }
+
+      const entity = JsonEntityStore.fromMethod(MyController, "test");
+
+      expect(entity.operation.isRedirection()).toBe(true);
+      expect(entity.operation.isRedirection(302)).toBe(true);
+      expect(entity.operation.isRedirection(200)).toBe(false);
+    });
+  });
+  describe("getContentTypeOf()", () => {
+    it("should return the content type of", () => {
+      @Path("/")
+      class MyController {
+        @Get("/")
+        @(Returns(200, String).ContentType("text/html"))
+        test() {}
+      }
+
+      const entity = JsonEntityStore.fromMethod(MyController, "test");
+
+      expect(entity.operation.getContentTypeOf(200)).toEqual("text/html");
+      expect(entity.operation.getContentTypeOf(201)).toEqual(undefined);
+    });
+  });
+  describe("when custom parameter is used", () => {
+    it("should not generate invalid parameter", () => {
+      class MyController {
+        @OperationPath("GET", "/")
+        method(@In("custom") req: any, @In("body") type: string) {}
+      }
+
+      expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+        paths: {
+          "/": {
+            get: {
+              operationId: "myControllerMethod",
+              parameters: [],
+              requestBody: {
+                content: {
+                  "application/json": {
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                },
+                required: false
+              },
+              responses: {
+                "200": {
+                  description: "Success"
+                }
+              },
+              tags: ["MyController"]
+            }
+          }
+        },
+        tags: [
+          {
+            name: "MyController"
+          }
+        ]
+      });
+    });
+  });
+});