@tsed/schema 8.0.0 → 8.0.2

package/src/domain/JsonOperation.ts

@@ -0,0 +1,219 @@
+import {deepMerge, uniq, uniqBy} from "@tsed/core";
+import {OpenSpecSecurity, OpenSpecTag, OS3Operation} from "@tsed/openspec";
+
+import {JsonHeader} from "../interfaces/JsonOpenSpec.js";
+import {isRedirectionStatus, isSuccessStatus} from "../utils/isSuccessStatus.js";
+import {JsonMap} from "./JsonMap.js";
+import {JsonParameter} from "./JsonParameter.js";
+import {JsonResponse} from "./JsonResponse.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+export interface JsonMethodPath {
+  path: string | RegExp;
+  method: string;
+
+  [key: string]: any;
+}
+
+export interface JsonOperationOptions extends OS3Operation<JsonSchema, JsonParameter, JsonMap<JsonResponse>> {
+  consumes: string[];
+  produces: string[];
+}
+
+export class JsonOperation extends JsonMap<JsonOperationOptions> {
+  $kind: string = "operation";
+
+  readonly operationPaths: Map<string, JsonMethodPath> = new Map();
+  #status: number;
+  #redirection: boolean = false;
+
+  constructor(obj: Partial<JsonOperationOptions> = {}) {
+    super({parameters: [], responses: new JsonMap(), ...obj});
+  }
+
+  get response(): JsonResponse | undefined {
+    return this.getResponses().get(this.getStatus().toString());
+  }
+
+  get status() {
+    return this.#status;
+  }
+
+  tags(tags: OpenSpecTag[]): this {
+    super.set("tags", tags);
+
+    return this;
+  }
+
+  addTags(tags: OpenSpecTag[]) {
+    tags = uniqBy([...(this.get("tags") || []), ...tags], "name");
+
+    return this.tags(tags);
+  }
+
+  summary(summary: string): this {
+    super.set("summary", summary);
+
+    return this;
+  }
+
+  operationId(operationId: string): this {
+    this.set("operationId", operationId);
+
+    return this;
+  }
+
+  responses(responses: JsonMap<any>): this {
+    this.set("responses", responses);
+
+    return this;
+  }
+
+  defaultStatus(status: number) {
+    this.#status = status;
+
+    return this;
+  }
+
+  getStatus() {
+    return this.#status || 200;
+  }
+
+  setRedirection(status = 302) {
+    this.#redirection = true;
+    this.#status = status;
+    return this;
+  }
+
+  isRedirection(status?: number) {
+    if (this.#redirection) {
+      if (status) {
+        return isRedirectionStatus(status);
+      }
+    }
+
+    return this.#redirection;
+  }
+
+  addResponse(statusCode: string | number, response: JsonResponse) {
+    if ((isSuccessStatus(statusCode) || isRedirectionStatus(statusCode)) && !this.#status) {
+      const res = this.getResponseOf(200);
+
+      this.getResponses().set(statusCode.toString(), res).delete("200");
+
+      this.defaultStatus(Number(statusCode));
+    }
+
+    const currentCode = statusCode === "default" ? this.getStatus().toString() : statusCode.toString();
+    const currentResponse = this.getResponses().get(currentCode);
+
+    if (!currentResponse) {
+      response.status = Number(currentCode);
+      this.getResponses().set(currentCode, response);
+    } else {
+      response.forEach((value, key) => {
+        if (!["content"].includes(key)) {
+          currentResponse.set(key, deepMerge(currentResponse.get(key), value));
+        }
+      });
+      currentResponse.status = Number(currentCode);
+    }
+
+    return this;
+  }
+
+  getResponses() {
+    return this.get("responses") as JsonMap<JsonResponse>;
+  }
+
+  getResponseOf(status: number | string): JsonResponse {
+    return (status === "default" ? this.response : this.getResponses().get(String(status))) || new JsonResponse();
+  }
+
+  ensureResponseOf(status: number | string): JsonResponse {
+    this.addResponse(status, this.getResponseOf(status));
+    return this.getResponseOf(status);
+  }
+
+  getHeadersOf(status: number): Record<string, JsonHeader & {example: string}> {
+    return this.getResponseOf(status).get("headers") || {};
+  }
+
+  getContentTypeOf(status: number): any {
+    return [...this.getResponseOf(status).get("content").keys()].slice(-1)[0];
+  }
+
+  security(security: OpenSpecSecurity): this {
+    this.set("security", security);
+
+    return this;
+  }
+
+  addSecurityScopes(name: string, scopes: string[]) {
+    const security = this.get("security") || {};
+    security[name] = uniq([...(security[name] || []), ...scopes]);
+
+    return this.security(security);
+  }
+
+  description(description: string): this {
+    super.set("description", description);
+
+    return this;
+  }
+
+  deprecated(deprecated: boolean): this {
+    super.set("deprecated", deprecated);
+
+    return this;
+  }
+
+  parameters(parameters: JsonParameter[]): this {
+    super.set("parameters", parameters);
+
+    return this;
+  }
+
+  addParameter(index: number, parameter: JsonParameter) {
+    if (index === -1) {
+      index = this.get("parameters").length;
+    }
+    this.get("parameters")[index] = parameter;
+  }
+
+  consumes(consumes: string[]): this {
+    super.set("consumes", consumes);
+
+    return this;
+  }
+
+  produces(produces: string[]): this {
+    super.set("produces", produces);
+
+    return this;
+  }
+
+  addProduce(produce: string) {
+    const produces = uniq([].concat(this.get("produces"), produce as never)).filter(Boolean);
+
+    this.set("produces", produces);
+  }
+
+  addOperationPath(method: string, path: string | RegExp, options: any = {}) {
+    this.operationPaths.set(String(method) + String(path), {
+      ...options,
+      method,
+      path
+    });
+
+    return this;
+  }
+
+  getAllowedOperationPath(allowedVerbs?: string[]) {
+    if (!allowedVerbs) {
+      return [...this.operationPaths.values()];
+    }
+
+    return [...this.operationPaths.values()].filter(({method}) => method && allowedVerbs.includes(method.toUpperCase()));
+  }
+}

package/src/domain/JsonOperationPathsMap.ts

@@ -0,0 +1,16 @@
+import {OperationVerbs} from "../constants/OperationVerbs.js";
+import {JsonMethodPath} from "./JsonOperation.js";
+
+export class JsonOperationPathsMap extends Map<string, JsonMethodPath> {
+  $kind: string = "operationPaths";
+  readonly $isJsonDocument = true;
+
+  setOperationPath(operationPath: JsonMethodPath) {
+    // if (operationPath.method !== OperationVerbs.CUSTOM) {
+    const key = this.getKey(operationPath.method, operationPath.path);
+    this.set(key, operationPath);
+    // }
+  }
+
+  protected getKey = (method: string, path: any) => `${method}-${path}`;
+}

package/src/domain/JsonOperationRoute.spec.ts

@@ -0,0 +1,109 @@
+import {BodyParams} from "@tsed/platform-params";
+
+import {Name} from "../decorators/common/name.js";
+import {Get} from "../decorators/operations/route.js";
+import {JsonEntityStore} from "./JsonEntityStore.js";
+import {JsonOperation} from "./JsonOperation.js";
+import {JsonOperationRoute} from "./JsonOperationRoute.js";
+
+describe("JsonOperationRoute", () => {
+  it("should create JsonOperationRoute instance", () => {
+    class Test {
+      @Get("/")
+      get() {}
+    }
+
+    const endpoint = JsonEntityStore.fromMethod(Test, "get");
+    const operationRoute = new JsonOperationRoute({
+      token: Test,
+      endpoint,
+      operationPath: {method: "GET", path: "/"},
+      basePath: "/base"
+    });
+
+    expect(operationRoute.operationPath).toEqual({
+      method: "GET",
+      path: "/"
+    });
+    expect(operationRoute.method).toEqual("GET");
+    expect(operationRoute.path).toEqual("/");
+    expect(operationRoute.fullPath).toEqual("/base");
+    expect(operationRoute.url).toEqual("/base");
+    expect(operationRoute.name).toEqual("Test.get()");
+    expect(operationRoute.className).toEqual("Test");
+    expect(operationRoute.methodClassName).toEqual("get");
+    expect(operationRoute.propertyKey).toEqual("get");
+    expect(operationRoute.propertyName).toEqual("get");
+    expect(operationRoute.operation).toBeInstanceOf(JsonOperation);
+    expect(operationRoute.operationId).toBe("get");
+    expect(operationRoute.parameters).toEqual([]);
+  });
+  it("should create JsonOperationRoute instance (with alias naming)", () => {
+    @Name("Testify")
+    class Test {
+      @Get("/")
+      @Name("getify")
+      get() {}
+    }
+
+    const endpoint = JsonEntityStore.fromMethod(Test, "get");
+    const operationRoute = new JsonOperationRoute({
+      token: Test,
+      endpoint,
+      operationPath: {method: "GET", path: "/"},
+      basePath: "/base"
+    });
+
+    expect(operationRoute.operationPath).toEqual({
+      method: "GET",
+      path: "/"
+    });
+    expect(operationRoute.method).toEqual("GET");
+    expect(operationRoute.path).toEqual("/");
+    expect(operationRoute.fullPath).toEqual("/base");
+    expect(operationRoute.url).toEqual("/base");
+    expect(operationRoute.name).toEqual("Test.get()");
+    expect(operationRoute.className).toEqual("Test");
+    expect(operationRoute.methodClassName).toEqual("get");
+    expect(operationRoute.propertyKey).toEqual("get");
+    expect(operationRoute.propertyName).toEqual("get");
+    expect(operationRoute.operation).toBeInstanceOf(JsonOperation);
+    expect(operationRoute.operationId).toBe("get");
+  });
+  it("should create operation with parameter", () => {
+    @Name("Testify")
+    class Test {
+      @Get("/")
+      @Name("getify")
+      get(@BodyParams() body: string) {}
+    }
+
+    const endpoint = JsonEntityStore.fromMethod(Test, "get");
+    const operationRoute = new JsonOperationRoute({
+      token: Test,
+      endpoint,
+      operationPath: {method: "GET", path: "/"},
+      basePath: "/base"
+    });
+
+    expect(operationRoute.operationPath).toEqual({
+      method: "GET",
+      path: "/"
+    });
+    expect(operationRoute.method).toEqual("GET");
+    expect(operationRoute.path).toEqual("/");
+    expect(operationRoute.fullPath).toEqual("/base");
+    expect(operationRoute.url).toEqual("/base");
+    expect(operationRoute.name).toEqual("Test.get()");
+    expect(operationRoute.className).toEqual("Test");
+    expect(operationRoute.methodClassName).toEqual("get");
+    expect(operationRoute.propertyKey).toEqual("get");
+    expect(operationRoute.propertyName).toEqual("get");
+    expect(operationRoute.operation).toBeInstanceOf(JsonOperation);
+    expect(operationRoute.operationId).toBe("get");
+    expect(operationRoute.paramsTypes).toEqual({
+      BODY: true
+    });
+    expect(operationRoute.has("BODY")).toEqual(true);
+  });
+});

package/src/domain/JsonOperationRoute.ts

@@ -0,0 +1,75 @@
+import {Type} from "@tsed/core";
+
+import {concatPath} from "../utils/concatPath.js";
+import {JsonMethodStore} from "./JsonMethodStore.js";
+import {JsonMethodPath, JsonOperation} from "./JsonOperation.js";
+
+export class JsonOperationRoute<Entity extends JsonMethodStore = JsonMethodStore> {
+  readonly token: Type<any>;
+  readonly endpoint: Entity;
+  readonly operationPath?: JsonMethodPath;
+  readonly basePath?: string;
+  readonly paramsTypes: Record<string, boolean>;
+
+  constructor(options: Partial<JsonOperationRoute>) {
+    Object.assign(this, options);
+
+    this.paramsTypes = this.endpoint.getParamTypes();
+  }
+
+  get url() {
+    return this.fullPath;
+  }
+
+  get path() {
+    return this.operationPath?.path;
+  }
+
+  get fullPath() {
+    return concatPath(this.basePath, this.path as any);
+  }
+
+  get method() {
+    return this.operationPath?.method || "USE";
+  }
+
+  get name() {
+    return `${this.endpoint.targetName}.${this.methodClassName}()`;
+  }
+
+  get className() {
+    return this.endpoint.targetName;
+  }
+
+  get methodClassName() {
+    return this.propertyKey;
+  }
+
+  get parameters() {
+    return this.endpoint.parameters;
+  }
+
+  get propertyKey() {
+    return String(this.endpoint.propertyKey);
+  }
+
+  get propertyName() {
+    return this.endpoint.propertyName;
+  }
+
+  get store() {
+    return this.endpoint.store;
+  }
+
+  get operation(): JsonOperation {
+    return this.endpoint.operation as JsonOperation;
+  }
+
+  get operationId() {
+    return this.operation.get("operationId") || this.endpoint.propertyKey;
+  }
+
+  has(key: string) {
+    return this.paramsTypes[key];
+  }
+}

package/src/domain/JsonParameter.ts

@@ -0,0 +1,70 @@
+import {Type} from "@tsed/core";
+import {OpenSpecHash, OpenSpecRef, OS3Example, OS3Parameter} from "@tsed/openspec";
+
+import {JsonSchemaOptions} from "../interfaces/JsonSchemaOptions.js";
+import {execMapper} from "../registries/JsonSchemaMapperContainer.js";
+import {NestedGenerics} from "../utils/generics.js";
+import {JsonMap} from "./JsonMap.js";
+import {formatParameterType} from "./JsonParameterTypes.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+export class JsonParameter extends JsonMap<OS3Parameter<JsonSchema>> implements NestedGenerics {
+  $kind = "operationInParameter";
+
+  nestedGenerics: Type<any>[][] = [];
+  groups: string[];
+  groupsName: string;
+  $schema: JsonSchema;
+  expression: string;
+
+  getName() {
+    const name = this.get("name");
+
+    if (this.get("in") === "files") {
+      return name.split(".")[0];
+    }
+
+    return name;
+  }
+
+  name(name: string): this {
+    this.set("name", name);
+
+    return this;
+  }
+
+  examples(examples: OpenSpecHash<OS3Example | OpenSpecRef>) {
+    super.set("examples", examples);
+
+    return this;
+  }
+
+  description(description: string): this {
+    this.set("description", description);
+
+    return this;
+  }
+
+  in(inType: string, expression: string | any = ""): this {
+    this.set("in", formatParameterType(inType));
+    this.expression = expression;
+
+    return this;
+  }
+
+  required(required: boolean): this {
+    this.set("required", required);
+
+    return this;
+  }
+
+  schema(schema: JsonSchema): this {
+    this.$schema = schema;
+
+    return this;
+  }
+
+  toJSON(options?: JsonSchemaOptions) {
+    return execMapper("operationInParameter", [this], options);
+  }
+}

package/src/domain/JsonParameterStore.spec.ts

@@ -0,0 +1,212 @@
+import {prototypeOf, Store} from "@tsed/core";
+
+import {Allow} from "../decorators/common/allow.js";
+import {Required} from "../decorators/common/required.js";
+import {In} from "../decorators/operations/in.js";
+import {Path} from "../decorators/operations/path.js";
+import {Get} from "../decorators/operations/route.js";
+import {getJsonEntityStore} from "../utils/getJsonEntityStore.js";
+import {JsonClassStore} from "./JsonClassStore.js";
+import {JsonMethodStore} from "./JsonMethodStore.js";
+import {JsonParameterStore} from "./JsonParameterStore.js";
+import {JsonParameterTypes} from "./JsonParameterTypes.js";
+
+describe("JsonParameterStore", () => {
+  describe("new JsonParameterStore", () => {
+    it("should load entities", () => {
+      class TestDynamicUrlCtrl {
+        async get(id: string) {}
+      }
+
+      const entity = getJsonEntityStore(prototypeOf(TestDynamicUrlCtrl), "get", 0);
+
+      expect(entity).toBeInstanceOf(JsonParameterStore);
+      expect(entity.parent).toBeInstanceOf(JsonMethodStore);
+      expect(entity.parent.parent).toBeInstanceOf(JsonClassStore);
+      expect(entity.parent.parent.parent).toBeInstanceOf(JsonClassStore);
+      expect(entity.nestedGenerics).toEqual([]);
+      expect(entity.required).toBe(false);
+      expect(entity.isRequired("")).toBe(false);
+      expect(entity.allowedRequiredValues).toEqual([]);
+    });
+  });
+  describe("getParams()", () => {
+    it("should returns params (body + path)", () => {
+      // GIVEN
+      @Path("/")
+      class Test {
+        @Get("/")
+        test(@In("body") body: any) {}
+      }
+
+      // WHEN
+      const result = JsonParameterStore.getParams(prototypeOf(Test), "test");
+
+      // THEN
+      expect(result[0].parameter.get("in")).toEqual("body");
+    });
+    it("should returns params (body)", () => {
+      // GIVEN
+      class Test {
+        @Get("/")
+        test(@In(JsonParameterTypes.BODY) body: any) {}
+      }
+
+      // WHEN
+      const result = JsonParameterStore.getParams(prototypeOf(Test), "test");
+      // THEN
+
+      expect(result[0].parameter.get("in")).toEqual("body");
+    });
+    it("should returns params from inherited", () => {
+      // GIVEN
+      class BaseTest {
+        @Get("/")
+        list(@(In("query").Name("search")) search: string) {}
+
+        @Get("/")
+        base(@(In("query").Name("base")) test: string) {}
+      }
+
+      class Test extends BaseTest {
+        @Get("/")
+        test(@(In("query").Name("search")) search: string) {}
+
+        @Get("/")
+        base(@(In("query").Name("test")) search: string) {}
+      }
+
+      // WHEN
+      const result1 = JsonParameterStore.getParams(prototypeOf(Test), "list");
+      const result2 = JsonParameterStore.getParams(prototypeOf(Test), "test");
+      const result3 = JsonParameterStore.getParams(prototypeOf(Test), "unknown");
+      const result4 = JsonParameterStore.getParams(prototypeOf(Test), "base");
+
+      // THEN
+      expect(result1.length).toEqual(1);
+      expect(result2.length).toEqual(1);
+      expect(result3).toEqual([]);
+      expect(result4.length).toEqual(1);
+      expect(result4[0].token).toBe(Test);
+    });
+  });
+  describe("isRequired", () => {
+    describe("when property is required", () => {
+      it("should return the expected required state", () => {
+        class Test {
+          @Get("/")
+          test(@Required() @In(JsonParameterTypes.BODY) body: any) {}
+        }
+
+        const store = JsonParameterStore.get(Test, "test", 0);
+
+        expect(store.isRequired(0)).toEqual(false);
+        expect(store.isRequired("")).toEqual(true);
+        expect(store.isRequired(null)).toEqual(true);
+        expect(store.isRequired(undefined)).toEqual(true);
+      });
+    });
+
+    describe("when property is required and have allowed values", () => {
+      it("should validate the required values", () => {
+        class Test {
+          @Get("/")
+          test(@Required() @Allow(null) @In(JsonParameterTypes.BODY) body: any) {}
+        }
+
+        const store = JsonParameterStore.get(Test, "test", 0);
+
+        expect(store.allowedRequiredValues).toEqual([null]);
+        expect(store.isRequired(0)).toEqual(false);
+        expect(store.isRequired("")).toEqual(true);
+        expect(store.isRequired(null)).toEqual(false);
+        expect(store.isRequired(undefined)).toEqual(true);
+      });
+
+      it("should validate the required values (2)", () => {
+        class Test {
+          @Get("/")
+          test(@Required() @Allow("") @In(JsonParameterTypes.BODY) body: any) {}
+        }
+
+        const store = JsonParameterStore.get(Test, "test", 0);
+        store.required = true;
+
+        expect(store.allowedRequiredValues).toEqual([""]);
+        expect(store.isRequired(0)).toEqual(false);
+        expect(store.isRequired("")).toEqual(false);
+        expect(store.isRequired(null)).toEqual(true);
+        expect(store.isRequired(undefined)).toEqual(true);
+      });
+
+      it("should validate the required values (3)", () => {
+        class Test {
+          @Get("/")
+          test(@Required() @Allow("") @In(JsonParameterTypes.BODY) body: any) {}
+        }
+
+        const store = JsonParameterStore.get(Test, "test", 0);
+        store.required = true;
+
+        expect(store.allowedRequiredValues).toEqual([""]);
+        expect(store.isRequired(0)).toEqual(false);
+        expect(store.isRequired("")).toEqual(false);
+        expect(store.isRequired(null)).toEqual(true);
+        expect(store.isRequired(undefined)).toEqual(true);
+      });
+    });
+
+    describe("when property is not required", () => {
+      it("should validate values", () => {
+        class Test {
+          @Get("/")
+          test(@Required(false) @Allow("") @In(JsonParameterTypes.BODY) body: any) {}
+        }
+
+        const store = JsonParameterStore.get(Test, "test", 0);
+        store.required = false;
+
+        expect(store.isRequired(0)).toEqual(false);
+        expect(store.isRequired("")).toEqual(false);
+        expect(store.isRequired(null)).toEqual(false);
+        expect(store.isRequired(undefined)).toEqual(false);
+      });
+    });
+  });
+  describe("props", () => {
+    it("should return the required value", () => {
+      class Test {
+        method(arg1: any, arg2: any) {}
+      }
+
+      const paramMetadata = JsonParameterStore.get(Test, "method", 0);
+      paramMetadata.required = true;
+      paramMetadata.expression = "test";
+      paramMetadata.type = Test;
+
+      expect(paramMetadata.required).toEqual(true);
+
+      expect(paramMetadata.expression).toEqual("test");
+
+      expect(paramMetadata.collectionType).toEqual(undefined);
+      expect(paramMetadata.type).toEqual(Test);
+      expect(paramMetadata.index).toEqual(0);
+      expect(paramMetadata.store).toBeInstanceOf(Store);
+    });
+  });
+  describe("as a service", () => {
+    it("should return the service", () => {
+      class Test {
+        method(arg1: any, arg2: any) {}
+      }
+
+      const paramMetadata = JsonParameterStore.get(Test, "method", 0);
+      paramMetadata.required = true;
+      paramMetadata.expression = "test";
+      paramMetadata.type = Test;
+      paramMetadata.paramType = "ERR";
+
+      expect(paramMetadata.paramType).toEqual("ERR");
+    });
+  });
+});