@tsed/schema 8.0.1 → 8.0.3

package/src/domain/JsonParameterStore.ts

@@ -0,0 +1,138 @@
+import {ancestorsOf, DecoratorTypes, isClass, isCollection, isMethodDescriptor, Metadata, prototypeOf, Type} from "@tsed/core";
+
+import {JsonEntityComponent} from "../decorators/config/jsonEntityComponent.js";
+import {JsonEntityStore, JsonEntityStoreOptions} from "./JsonEntityStore.js";
+import type {JsonMethodStore} from "./JsonMethodStore.js";
+import {JsonParameter} from "./JsonParameter.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+export interface JsonParameterStoreOptions extends JsonEntityStoreOptions {
+  dataPath?: string;
+  paramType?: string;
+  expression?: string;
+}
+
+export interface PipeMethods<T = any, R = any> {
+  transform(value: T, metadata: JsonParameterStore): R;
+}
+
+@JsonEntityComponent(DecoratorTypes.PARAM)
+export class JsonParameterStore extends JsonEntityStore {
+  public paramType: string;
+  public expression: string;
+  public dataPath: string;
+  /**
+   * Define pipes can be called by the framework to transform input parameter
+   */
+  public pipes: Type<PipeMethods>[];
+  /**
+   * Ref to JsonParameter when the decorated object is a parameter.
+   */
+  readonly parameter: JsonParameter = new JsonParameter();
+  readonly parent: JsonMethodStore = JsonEntityStore.fromMethod(this.target, this.propertyKey);
+
+  constructor(options: JsonParameterStoreOptions) {
+    super(options);
+    this.pipes = options.pipes || [];
+    this.paramType = options.paramType || this.paramType;
+    this.expression = options.expression || this.expression;
+    this.dataPath = options.dataPath || this.dataPath;
+  }
+
+  get nestedGenerics(): Type<any>[][] {
+    return this.parameter.nestedGenerics;
+  }
+
+  set nestedGenerics(nestedGenerics: Type<any>[][]) {
+    this.parameter.nestedGenerics = nestedGenerics;
+  }
+
+  /**
+   * Return the required state.
+   * @returns {boolean}
+   */
+  get required(): boolean {
+    return !!this.parameter.get("required");
+  }
+
+  set required(value: boolean) {
+    this.parameter.required(value);
+  }
+
+  get allowedRequiredValues() {
+    return this.schema.$allow;
+  }
+
+  static getParams<T extends JsonParameterStore = JsonParameterStore>(target: Type<any>, propertyKey: string | symbol): T[] {
+    const params: T[] = [];
+
+    const klass = ancestorsOf(target)
+      .reverse()
+      .find((target) => {
+        return isMethodDescriptor(target, propertyKey) && JsonEntityStore.fromMethod(target, propertyKey).children.size;
+      });
+
+    if (klass) {
+      JsonEntityStore.fromMethod(klass, propertyKey).children.forEach((param: T, index) => {
+        params[+index] = param;
+      });
+
+      return params;
+    }
+
+    return [];
+  }
+
+  static get(target: Type<any>, propertyKey: string | symbol, index: number) {
+    return JsonEntityStore.from<JsonParameterStore>(prototypeOf(target), propertyKey, index);
+  }
+
+  /**
+   * Check precondition between value, required and allowedRequiredValues to know if the entity is required.
+   * @param value
+   * @returns {boolean}
+   */
+  isRequired(value: any): boolean {
+    return this.required && [undefined, null, ""].includes(value) && !this.allowedRequiredValues.includes(value);
+  }
+
+  protected getSchema(type: any) {
+    if (isCollection(type) || !isClass(type)) {
+      return JsonSchema.from({
+        type
+      });
+    }
+
+    return JsonEntityStore.from(type).schema;
+  }
+
+  protected build() {
+    if (!this._type) {
+      const type: any = Metadata.getParamTypes(prototypeOf(this.target), this.propertyKey)[this.index!];
+
+      this.buildType(type);
+    }
+
+    this._type = this._type || Object;
+
+    if (!this._schema) {
+      this.parent.children.set(this.index!, this);
+
+      this._schema = this.getSchema(this.collectionType || this.type);
+
+      this.parameter.schema(this._schema);
+
+      if (this.collectionType) {
+        this._schema.itemSchema(this.getSchema(this.type));
+      }
+
+      this.parent.operation.addParameter(this.index as number, this.parameter);
+    }
+  }
+}
+
+/**
+ * @alias JsonParameterStore
+ */
+export type ParamMetadata = JsonParameterStore;
+export const ParamMetadata = JsonParameterStore;

package/src/domain/JsonParameterTypes.spec.ts

@@ -0,0 +1,12 @@
+import {isParameterType} from "../index.js";
+
+describe("JsonParameterType", () => {
+  describe("isParameterType", () => {
+    it("should return true", () => {
+      expect(isParameterType("query")).toBe(true);
+    });
+    it("should return false", () => {
+      expect(isParameterType("req")).toBe(false);
+    });
+  });
+});

package/src/domain/JsonParameterTypes.ts

@@ -0,0 +1,20 @@
+export enum JsonParameterTypes {
+  BODY = "body",
+  PATH = "path",
+  QUERY = "query",
+  HEADER = "header",
+  COOKIES = "cookie",
+  FILES = "files"
+}
+/**
+ * @ignore
+ */
+export function formatParameterType(type: any): any {
+  return String(type).toLowerCase().replace("raw_", "").replace("cookies", "cookie");
+}
+/**
+ * @ignore
+ */
+export function isParameterType(type: string) {
+  return Object.values(JsonParameterTypes).includes(formatParameterType(type) as any);
+}

package/src/domain/JsonPropertyStore.spec.ts

@@ -0,0 +1,177 @@
+import {prototypeOf} from "@tsed/core";
+
+import {Allow, JsonClassStore, JsonPropertyStore, Required} from "../index.js";
+import {getJsonEntityStore} from "../utils/getJsonEntityStore.js";
+
+describe("JsonParameterStore", () => {
+  it("should create entity with required value", () => {
+    class TestDynamicUrlCtrl {
+      @Required()
+      prop: string;
+    }
+
+    const entity = getJsonEntityStore(prototypeOf(TestDynamicUrlCtrl), "prop");
+
+    expect(entity).toBeInstanceOf(JsonPropertyStore);
+    expect(entity.parent).toBeInstanceOf(JsonClassStore);
+    expect(entity.parent.parent.parent).toBeInstanceOf(JsonClassStore);
+    expect(entity.nestedGenerics).toEqual([]);
+    expect(entity.required).toBe(true);
+    expect(entity.isRequired("")).toBe(true);
+    expect(entity.allowedRequiredValues).toEqual([]);
+    expect(entity.isDiscriminatorKey()).toEqual(false);
+
+    entity.required = false;
+    expect(entity.required).toBe(false);
+
+    entity.required = true;
+    expect(entity.required).toBe(true);
+  });
+  it("should create entity with allowed value", () => {
+    class TestDynamicUrlCtrl {
+      @Required(true, "")
+      prop: string;
+    }
+
+    const entity = getJsonEntityStore(prototypeOf(TestDynamicUrlCtrl), "prop");
+
+    expect(entity).toBeInstanceOf(JsonPropertyStore);
+    expect(entity.parent).toBeInstanceOf(JsonClassStore);
+    expect(entity.parent.parent.parent).toBeInstanceOf(JsonClassStore);
+    expect(entity.nestedGenerics).toEqual([]);
+    expect(entity.required).toBe(true);
+    expect(entity.isRequired("")).toBe(false);
+    expect(entity.allowedRequiredValues).toEqual([""]);
+
+    entity.required = false;
+    expect(entity.required).toBe(false);
+
+    entity.required = true;
+    expect(entity.required).toBe(true);
+  });
+  describe("required() and allowRequiredValues", () => {
+    it("should return the required value", () => {
+      class Test {
+        @Required(true)
+        @Allow(null, "")
+        test: string;
+      }
+
+      const jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+      jsonPropertyStore.required = true;
+      jsonPropertyStore.type = Test;
+
+      expect(jsonPropertyStore.required).toEqual(true);
+
+      expect(jsonPropertyStore.collectionType).toEqual(undefined);
+      expect(jsonPropertyStore.type).toEqual(Test);
+      expect(jsonPropertyStore.isCollection).toEqual(false);
+    });
+  });
+
+  describe("isRequired", () => {
+    describe("when property is required", () => {
+      class Test {
+        @Required(true)
+        test: string;
+      }
+
+      let jsonPropertyStore: JsonPropertyStore;
+
+      beforeAll(() => {
+        jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+        jsonPropertyStore.required = true;
+      });
+      it("should return false (value 0)", () => {
+        expect(jsonPropertyStore.isRequired(0)).toEqual(false);
+      });
+
+      it("should return true (value '')", () => {
+        expect(jsonPropertyStore.isRequired("")).toEqual(true);
+      });
+      it("should return true (value null)", () => {
+        expect(jsonPropertyStore.isRequired(null)).toEqual(true);
+      });
+      it("should return true (value undefined)", () => {
+        expect(jsonPropertyStore.isRequired(undefined)).toEqual(true);
+      });
+    });
+
+    describe("when property is required and have allowed values", () => {
+      it("should validate the required values", () => {
+        class Test {
+          @Required()
+          @Allow(null)
+          test: string;
+        }
+
+        let jsonPropertyStore: JsonPropertyStore;
+        jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+
+        expect(jsonPropertyStore.allowedRequiredValues).toEqual([null]);
+        expect(jsonPropertyStore.isRequired(0)).toEqual(false);
+        expect(jsonPropertyStore.isRequired("")).toEqual(true);
+        expect(jsonPropertyStore.isRequired(null)).toEqual(false);
+        expect(jsonPropertyStore.isRequired(undefined)).toEqual(true);
+      });
+
+      it("should validate the required values (2)", () => {
+        class Test {
+          @Allow("")
+          test: string;
+        }
+
+        let jsonPropertyStore: JsonPropertyStore;
+        jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+
+        expect(jsonPropertyStore.allowedRequiredValues).toEqual([""]);
+        expect(jsonPropertyStore.isRequired(0)).toEqual(false);
+        expect(jsonPropertyStore.isRequired("")).toEqual(false);
+        expect(jsonPropertyStore.isRequired(null)).toEqual(true);
+        expect(jsonPropertyStore.isRequired(undefined)).toEqual(true);
+      });
+
+      it("should validate the required values (3)", () => {
+        class Test {
+          @Allow("")
+          test: string;
+        }
+
+        let jsonPropertyStore: JsonPropertyStore;
+        jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+
+        expect(jsonPropertyStore.allowedRequiredValues).toEqual([""]);
+        expect(jsonPropertyStore.isRequired(0)).toEqual(false);
+        expect(jsonPropertyStore.isRequired("")).toEqual(false);
+        expect(jsonPropertyStore.isRequired(null)).toEqual(true);
+        expect(jsonPropertyStore.isRequired(undefined)).toEqual(true);
+      });
+    });
+
+    describe("when property is not required", () => {
+      it("should validate values", () => {
+        class Test {
+          @Required(false)
+          test: string;
+        }
+
+        const jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+        jsonPropertyStore.required = false;
+        expect(jsonPropertyStore.isRequired(0)).toEqual(false);
+        expect(jsonPropertyStore.isRequired("")).toEqual(false);
+        expect(jsonPropertyStore.isRequired(null)).toEqual(false);
+        expect(jsonPropertyStore.isRequired(undefined)).toEqual(false);
+      });
+    });
+  });
+  describe("get()", () => {
+    class Test {
+      test: string;
+    }
+
+    it("should return the jsonPropertyStore", () => {
+      const jsonPropertyStore = JsonPropertyStore.get(Test, "test");
+      expect(jsonPropertyStore).toBeInstanceOf(JsonPropertyStore);
+    });
+  });
+});

package/src/domain/JsonPropertyStore.ts

@@ -0,0 +1,92 @@
+import {DecoratorTypes, Metadata, prototypeOf, Type} from "@tsed/core";
+
+import {JsonEntityComponent} from "../decorators/config/jsonEntityComponent.js";
+import type {JsonClassStore} from "./JsonClassStore.js";
+import {JsonEntityStore} from "./JsonEntityStore.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+@JsonEntityComponent(DecoratorTypes.PROP)
+export class JsonPropertyStore extends JsonEntityStore {
+  readonly parent: JsonClassStore = JsonEntityStore.from(this.target);
+
+  /**
+   * Return the required state.
+   * @returns {boolean}
+   */
+  get required(): boolean {
+    return this.parent.schema.isRequired(this.propertyKey as string);
+  }
+
+  /**
+   * Change the state of the required data.
+   * @param value
+   */
+  set required(value: boolean) {
+    if (value) {
+      this.parent.schema.addRequired(this.propertyKey as string);
+    } else {
+      this.parent.schema.removeRequired(this.propertyKey as string);
+    }
+  }
+
+  get allowedRequiredValues() {
+    return this.schema.$allow;
+  }
+
+  discriminatorKey() {
+    this.parent.schema.discriminatorKey(String(this.propertyKey));
+    this.itemSchema.isDiscriminatorKey = true;
+    return this;
+  }
+
+  isDiscriminatorKey() {
+    return this.itemSchema.isDiscriminatorKey;
+  }
+
+  /**
+   * Check precondition between value, required and allowedRequiredValues to know if the entity is required.
+   * @param value
+   * @returns {boolean}
+   */
+  isRequired(value: any): boolean {
+    return this.required && [undefined, null, ""].includes(value) && !this.allowedRequiredValues.includes(value);
+  }
+
+  protected build() {
+    if (!this._type) {
+      this.buildType(Metadata.getType(prototypeOf(this.target), this.propertyKey));
+    }
+
+    this._type = this._type || Object;
+
+    const properties = this.parent.schema.get("properties");
+
+    let schema: JsonSchema = properties[this.propertyName];
+
+    if (!schema) {
+      this.parent.children.set(this.propertyName, this);
+
+      schema = JsonSchema.from({
+        type: this.collectionType || this.type
+      });
+
+      if (this.collectionType) {
+        schema.itemSchema(this.type);
+      }
+    }
+
+    this.parent.schema.addProperty(this.propertyName, schema);
+
+    this._schema = schema;
+  }
+
+  static get(target: Type<any>, propertyKey: string | symbol) {
+    return JsonEntityStore.from<JsonPropertyStore>(prototypeOf(target), propertyKey);
+  }
+}
+
+/**
+ * @alias JsonPropertyStore
+ */
+export type PropertyMetadata = JsonPropertyStore;
+export const PropertyMetadata = JsonPropertyStore;

package/src/domain/JsonRequestBody.ts

@@ -0,0 +1,47 @@
+import {OpenSpecHash, OS3MediaType, OS3RequestBody} from "@tsed/openspec";
+
+import {toJsonMapCollection} from "../utils/toJsonMapCollection.js";
+import {JsonMap} from "./JsonMap.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+export type JsonRequestBodyOptions = OS3RequestBody<JsonSchema>;
+
+export class JsonRequestBody extends JsonMap<JsonRequestBodyOptions> {
+  $kind = "operationRequestBody";
+
+  constructor(obj: Partial<JsonRequestBodyOptions> = {}) {
+    super(obj);
+
+    this.content(obj.content || ({} as any));
+  }
+
+  description(description: string): this {
+    this.set("description", description);
+
+    return this;
+  }
+
+  content(content: OpenSpecHash<OS3MediaType<JsonSchema>>) {
+    this.set("content", toJsonMapCollection(content));
+
+    return this;
+  }
+
+  addContent(mediaType: string, schema: JsonSchema, examples?: any) {
+    const content = this.get("content");
+    const mediaContent = new JsonMap();
+
+    mediaContent.set("schema", schema);
+    examples && mediaContent.set("examples", examples);
+
+    content.set(mediaType, mediaContent);
+
+    return this;
+  }
+
+  required(required: boolean): this {
+    this.set("required", required);
+
+    return this;
+  }
+}

package/src/domain/JsonResponse.spec.ts

@@ -0,0 +1,33 @@
+import {JsonResponse} from "./JsonResponse.js";
+
+describe("JsonResponse", () => {
+  describe("isBinary()", () => {
+    it("should return true when the response as application/octet-stream", () => {
+      const result = new JsonResponse({
+        content: {
+          "application/octet-stream": {
+            schema: {
+              format: "binary",
+              type: "string"
+            }
+          }
+        }
+      } as never);
+
+      expect(result.isBinary()).toEqual(true);
+    });
+    it("should return false when the response as application/json", () => {
+      const result = new JsonResponse({
+        content: {
+          "application/json": {
+            schema: {
+              type: "string"
+            }
+          }
+        }
+      } as never);
+
+      expect(result.isBinary()).toEqual(false);
+    });
+  });
+});

package/src/domain/JsonResponse.ts

@@ -0,0 +1,64 @@
+import {OS3MediaType, OS3Response} from "@tsed/openspec";
+
+import {JsonHeader} from "../interfaces/JsonOpenSpec.js";
+import {mapHeaders} from "../utils/mapHeaders.js";
+import {toJsonMapCollection} from "../utils/toJsonMapCollection.js";
+import {JsonMap} from "./JsonMap.js";
+import {JsonMedia} from "./JsonMedia.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+export type JsonResponseOptions = OS3Response<JsonSchema, string | JsonHeader>;
+
+export class JsonResponse extends JsonMap<JsonResponseOptions> {
+  $kind: string = "operationResponse";
+
+  status: number;
+
+  constructor(obj: Partial<JsonResponseOptions> = {}) {
+    super(obj);
+
+    this.content(obj.content || ({} as any));
+  }
+
+  description(description: string): this {
+    this.set("description", description);
+
+    return this;
+  }
+
+  headers(headers: Record<string, string | JsonHeader>): this {
+    this.set("headers", mapHeaders(headers));
+
+    return this;
+  }
+
+  content(content: Record<string, OS3MediaType<JsonSchema>>) {
+    this.set("content", toJsonMapCollection(content, JsonMedia));
+
+    return this;
+  }
+
+  getContent(): JsonMap<JsonMedia> {
+    return this.get("content")!;
+  }
+
+  getMedia(mediaType: string, create = true): JsonMedia {
+    create && this.addMedia(mediaType);
+
+    return this.getContent()?.get(mediaType) as any;
+  }
+
+  addMedia(mediaType: string) {
+    const content = this.get("content");
+
+    if (!content.has(mediaType)) {
+      content.set(mediaType, new JsonMedia());
+    }
+
+    return this;
+  }
+
+  isBinary() {
+    return this.getContent().has("application/octet-stream");
+  }
+}