@tsed/schema 8.0.0 → 8.0.2

package/src/decorators/common/readOnly.ts

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

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

@@ -0,0 +1,41 @@
+import {getJsonSchema} from "../../index.js";
+import {RecordOf} from "./recordOf.js";
+
+describe("RecordOf()", () => {
+  it("should store data", () => {
+    type keys = "one" | "two";
+
+    class Part {
+      prop: string;
+    }
+
+    type Parts = Record<keys, Part>;
+
+    class Test {
+      @RecordOf(Part, "one", "two")
+      parts: Parts;
+    }
+
+    expect(getJsonSchema(Test)).toEqual({
+      definitions: {
+        Part: {
+          type: "object"
+        }
+      },
+      type: "object",
+      properties: {
+        parts: {
+          properties: {
+            one: {
+              $ref: "#/definitions/Part"
+            },
+            two: {
+              $ref: "#/definitions/Part"
+            }
+          },
+          type: "object"
+        }
+      }
+    });
+  });
+});

package/src/decorators/common/recordOf.ts

@@ -0,0 +1,59 @@
+import {Schema} from "./schema.js";
+
+/**
+ * Constructs a json schema object type whose property keys are keys and whose property values are type.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * type keys = 'one' | 'two';
+ *
+ * class Part {
+ *   prop: string;
+ * }
+ *
+ * type Parts = Record<keys, Part>;
+ *
+ * class Test {
+ *   @RecordOf(Part, 'one', 'two')
+ *   parts: Parts;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *     "type": "object",
+ *     "properties": {
+ *         "one": {
+ *             "$ref": "#/components/schemas/Part"
+ *         },
+ *         "two": {
+ *             "$ref": "#/components/schemas/Part"
+ *         },
+ *     },
+ * }
+ * ```
+ *
+ * @param model
+ * @param keys
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export function RecordOf(model: any, ...keys: string[]) {
+  return Schema({
+    properties: {
+      ...keys.reduce((initial, key) => {
+        return {
+          ...initial,
+          [key]: model
+        };
+      }, {})
+    }
+  });
+}

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

@@ -0,0 +1,188 @@
+import {Ajv} from "ajv";
+
+import {validateModel} from "../../../test/helpers/validateModel.js";
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {getJsonSchema, MinLength} from "../../index.js";
+import {Property} from "../common/property.js";
+import {Required} from "./required.js";
+
+describe("@Required", () => {
+  it("should declare required field", () => {
+    // WHEN
+    class Model {
+      @Required()
+      num: number;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          type: "number"
+        }
+      },
+      required: ["num"],
+      type: "object"
+    });
+  });
+  it("should declare required field (false)", () => {
+    // WHEN
+    class Model {
+      @Required(false)
+      num: number;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          type: "number"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare required field on string property", () => {
+    // WHEN
+    class Model {
+      @Required()
+      prop: string;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        prop: {
+          minLength: 1,
+          type: "string"
+        }
+      },
+      required: ["prop"],
+      type: "object"
+    });
+  });
+  it("should declare required field on string property (minLength 3)", () => {
+    // WHEN
+    class Model {
+      @Required()
+      @MinLength(3)
+      prop: string;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        prop: {
+          minLength: 3,
+          type: "string"
+        }
+      },
+      required: ["prop"],
+      type: "object"
+    });
+  });
+  it("should declare required field with a model an null", () => {
+    // WHEN
+    class NestedModel {
+      @Property()
+      prop: string;
+    }
+
+    class Model {
+      @Required(true, 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);
+  });
+  it("should declare required field with custom error message", () => {
+    // WHEN
+    class Model {
+      @(Required().Error("custom message"))
+      num: number;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model, {customKeys: true});
+
+    expect(schema).toEqual({
+      errorMessage: {
+        required: {
+          num: "custom message"
+        }
+      },
+      properties: {
+        num: {
+          type: "number"
+        }
+      },
+      required: ["num"],
+      type: "object"
+    });
+
+    const result = validateModel({}, Model);
+
+    expect(result).toEqual([
+      {
+        instancePath: "",
+        keyword: "errorMessage",
+        message: "custom message",
+        params: {
+          errors: [
+            {
+              emUsed: true,
+              instancePath: "",
+              keyword: "required",
+              message: "must have required property 'num'",
+              params: {
+                missingProperty: "num"
+              },
+              schemaPath: "#/required"
+            }
+          ]
+        },
+        schemaPath: "#/errorMessage"
+      }
+    ]);
+  });
+});

package/src/decorators/common/required.ts

@@ -0,0 +1,50 @@
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {Allow} from "./allow.js";
+import {Optional} from "./optional.js";
+
+/**
+ * Add required annotation on Property or Parameter.
+ *
+ * The @@Required@@ decorator can be used on two cases.
+ *
+ * To decorate a parameters:
+ *
+ * ```typescript
+ * @Post("/")
+ * async method(@Required() @BodyParams("field") field: string) {}
+ * ```
+ *
+ * To decorate a model:
+ *
+ * ```typescript
+ * class Model {
+ *   @Required()
+ *   field: string;
+ * }
+ * ```
+ *
+ * ::: tip
+ * Required will throw a BadRequest when the given value is `null`, an empty string or `undefined`.
+ * :::
+ *
+ * ### Allow values
+ *
+ * In some case, you didn't want trigger a BadRequest when the value is an empty string for example.
+ * The decorator `@Allow()`, allow you to configure a value list for which there will be no exception.
+ *
+ * ```typescript
+ * class Model {
+ *   @Allow("") // add automatically required flag
+ *   field: string;
+ * }
+ * ```
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export const Required = withErrorMsg("required", (required: boolean = true, ...allowedRequiredValues: any[]) => {
+  return required ? Allow(...allowedRequiredValues) : Optional();
+});

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

@@ -0,0 +1,127 @@
+import {getJsonSchema, Required} from "../../index.js";
+import {Groups} from "./groups.js";
+import {RequiredGroups} from "./requiredGroups.js";
+
+class MyModel {
+  @Groups("!creation")
+  id: string;
+
+  @Required()
+  prop1: string;
+
+  @RequiredGroups("!patch")
+  @Required()
+  prop2: string;
+
+  @RequiredGroups("patch")
+  @Required()
+  prop3: string;
+}
+
+describe("@RequiredGroups", () => {
+  it("should have required fields filtered by groups (groups: false)", () => {
+    const spec = getJsonSchema(MyModel, {
+      groups: false
+    });
+
+    expect(spec).toEqual({
+      properties: {
+        id: {
+          type: "string"
+        },
+        prop1: {
+          minLength: 1,
+          type: "string"
+        },
+        prop2: {
+          minLength: 1,
+          type: "string"
+        },
+        prop3: {
+          minLength: 1,
+          type: "string"
+        }
+      },
+      required: ["prop1", "prop2", "prop3"],
+      type: "object"
+    });
+  });
+  it("should have required fields filtered by groups (groups: [])", () => {
+    const spec = getJsonSchema(MyModel, {
+      groups: []
+    });
+
+    expect(spec).toEqual({
+      properties: {
+        id: {
+          type: "string"
+        },
+        prop1: {
+          minLength: 1,
+          type: "string"
+        },
+        prop2: {
+          minLength: 1,
+          type: "string"
+        },
+        prop3: {
+          minLength: 1,
+          type: "string"
+        }
+      },
+      required: ["prop1", "prop2"],
+      type: "object"
+    });
+  });
+  it("should have required fields filtered by groups (groups: ['patch'])", () => {
+    const spec = getJsonSchema(MyModel, {
+      groups: ["patch"]
+    });
+
+    expect(spec).toEqual({
+      properties: {
+        id: {
+          type: "string"
+        },
+        prop1: {
+          minLength: 1,
+          type: "string"
+        },
+        prop2: {
+          minLength: 1,
+          type: "string"
+        },
+        prop3: {
+          minLength: 1,
+          type: "string"
+        }
+      },
+      required: ["prop1", "prop3"],
+      type: "object"
+    });
+  });
+  it("should have required fields filtered by groups (groups: ['!patch'])", () => {
+    const spec = getJsonSchema(MyModel, {
+      groups: ["!patch"]
+    });
+
+    expect(spec).toEqual({
+      properties: {
+        prop1: {
+          minLength: 1,
+          type: "string"
+        },
+        prop2: {
+          minLength: 1,
+          type: "string"
+        },
+        prop3: {
+          minLength: 1,
+          type: "string"
+        }
+      },
+      required: ["prop1", "prop2"],
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/requiredGroups.ts

@@ -0,0 +1,23 @@
+import {matchGroups} from "../../utils/matchGroups.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Apply groups validation strategy for required property.
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function RequiredGroups(...groups: string[]): PropertyDecorator {
+  return JsonEntityFn((entity) => {
+    entity.parent.schema.$hooks.on("requiredGroups", (required: string[], givenGroups: string[]) => {
+      if (matchGroups(groups, givenGroups)) {
+        return required.filter((key: string) => key !== entity.propertyKey);
+      }
+
+      return required;
+    });
+  });
+}

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

@@ -0,0 +1,23 @@
+import {getJsonSchema} from "../../index.js";
+import {Schema} from "./schema.js";
+
+describe("Schema()", () => {
+  it("should store data", () => {
+    class Test {
+      @Schema({
+        pattern: "a|b"
+      })
+      test: string;
+    }
+
+    expect(getJsonSchema(Test)).toEqual({
+      properties: {
+        test: {
+          pattern: "a|b",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/schema.ts

@@ -0,0 +1,64 @@
+import {JsonSchema, JsonSchemaObject} from "../../domain/JsonSchema.js";
+import {SpecTypes} from "../../domain/SpecTypes.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Write data formatted to JsonSchema.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * @Schema({title: "test"})
+ * class Model {
+ *    @Schema({formatMinimum: "1987-10-24"})
+ *    @Format("date")
+ *    birthDate: Date
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "title": "test",
+ *   "properties": {
+ *     "birthdate": {
+ *        "type": "string",
+ *        "format": "date",
+ *        "formatMinimum": "1987-10-24"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param partialSchema
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export function Schema(partialSchema: Partial<JsonSchemaObject> | JsonSchema) {
+  return JsonEntityFn((entity) => {
+    entity.schema.assign(partialSchema);
+  });
+}
+
+/**
+ * Apply specific schema depending on the spec version
+ * @param specType
+ * @param schema
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export function For(specType: SpecTypes, schema: any) {
+  return JsonEntityFn((entity) => {
+    entity.schema.set(specType, schema);
+  });
+}

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

@@ -0,0 +1,20 @@
+import {getJsonSchema, Title} from "../../index.js";
+
+describe("Title()", () => {
+  it("should store data", () => {
+    class Test {
+      @Title("Title")
+      test: string;
+    }
+
+    expect(getJsonSchema(Test)).toEqual({
+      properties: {
+        test: {
+          title: "Title",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/title.ts

@@ -0,0 +1,45 @@
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Add title metadata on the decorated element.
+ *
+ * ::: warning
+ * For v6 user, use @@Title@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Title("title")
+ *    id: string;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "id": {
+ *        "type": "string",
+ *        "title": "title"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {string} title
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export function Title(title: string) {
+  return JsonEntityFn((entity) => {
+    entity.schema.title(title);
+  });
+}

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

@@ -0,0 +1,22 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {TypeError} from "./typeError.js";
+
+describe("@TypeError", () => {
+  it("should declare type error message", () => {
+    // WHEN
+    @TypeError("foo should be a string")
+    class Model {
+      property: number;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model, {customKeys: true});
+
+    expect(schema).toEqual({
+      type: "object",
+      errorMessage: {
+        type: "foo should be a string"
+      }
+    });
+  });
+});

package/src/decorators/common/typeError.ts

@@ -0,0 +1,15 @@
+import {useDecorators} from "@tsed/core";
+
+import {ErrorMsg} from "./errorMsg.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Create a new custom formats validator
+ * @param name
+ * @param options
+ * @decorator
+ * @ajv
+ */
+export function TypeError(msg: string): ClassDecorator {
+  return JsonEntityFn(() => useDecorators(ErrorMsg({type: msg})));
+}