@tsed/schema 8.0.1 → 8.0.2

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

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

package/src/decorators/common/errorMsg.ts

@@ -0,0 +1,14 @@
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Add an error message to the property.
+ * @decorator
+ * @ajv
+ */
+export function ErrorMsg(obj: Record<string, string>) {
+  return JsonEntityFn((store) => {
+    // since errorMessage is a custom key, it is prefixed with a # to avoid conflict with JSON Schema keywords
+    const errorMessage = store.parentSchema.get("#errorMessage") || {};
+    store.parentSchema.customKey("errorMessage", {...errorMessage, ...obj});
+  });
+}

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

@@ -0,0 +1,93 @@
+import {descriptorOf, useDecorators} from "@tsed/core";
+
+import {Description, getSpec, In, Name, OperationPath, Path, Pattern, SpecTypes} from "../../index.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Example} from "./example.js";
+
+function ObjectID(name?: string) {
+  return useDecorators(name && Name(name), Pattern(/^[0-9a-fA-F]{24}$/), Description("An ObjectID"), Example("5ce7ad3028890bd71749d477"));
+}
+
+describe("@Example", () => {
+  it("should declare description on class", () => {
+    // WHEN
+    @Example({id: "id"})
+    class Model {}
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      examples: [{id: "id"}],
+      type: "object"
+    });
+  });
+  it("should declare example on params", () => {
+    // WHEN
+
+    @Path("/")
+    class MyController {
+      @OperationPath("GET", "/:id")
+      getMethod(
+        @In("path")
+        @Name("id")
+        @ObjectID()
+        id: string
+      ) {
+        return id;
+      }
+    }
+
+    // THEN
+    expect(getSpec(MyController)).toEqual({
+      paths: {
+        "/{id}": {
+          get: {
+            operationId: "myControllerGetMethod",
+            parameters: [
+              {
+                description: "An ObjectID",
+                in: "path",
+                name: "id",
+                required: true,
+                schema: {
+                  example: "5ce7ad3028890bd71749d477",
+                  pattern: "^[0-9a-fA-F]{24}$",
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should declare description on property", () => {
+    // WHEN
+
+    class Model {
+      @Example("Examples")
+      method: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        method: {
+          examples: ["Examples"],
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/example.ts

@@ -0,0 +1,18 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Add an example metadata on the decorated element.
+ *
+ * @decorator
+ * @swagger
+ * @schema
+ * @input
+ * @methodDecorator
+ * @classDecorator
+ */
+export function Example(...examples: any[]): Function {
+  return JsonEntityFn((store: JsonEntityStore) => {
+    store.schema.examples(examples);
+  });
+}

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

@@ -0,0 +1,101 @@
+import {getSpec, In, OperationPath, Path, Property, SpecTypes} from "../../index.js";
+import {Examples} from "./examples.js";
+
+class MyModel {
+  @Property()
+  id: string;
+}
+
+describe("@Examples", () => {
+  it("should declare example on body params", () => {
+    // WHEN
+    @Path("/")
+    class MyController {
+      @OperationPath("POST", "/:id")
+      getMethod(
+        @In("body")
+        @Examples({
+          Example1: {
+            description: "Example with hello1",
+            value: {test: "hello1"}
+          },
+          Example2: {
+            description: "Example with hello2",
+            value: {test: "hello2"}
+          }
+        })
+        model: MyModel
+      ) {
+        return model;
+      }
+    }
+
+    // THEN
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      components: {
+        schemas: {
+          MyModel: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/{id}": {
+          post: {
+            operationId: "myControllerGetMethod",
+            parameters: [
+              {
+                in: "path",
+                name: "id",
+                required: true,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            requestBody: {
+              content: {
+                "application/json": {
+                  examples: {
+                    Example1: {
+                      description: "Example with hello1",
+                      value: {
+                        test: "hello1"
+                      }
+                    },
+                    Example2: {
+                      description: "Example with hello2",
+                      value: {
+                        test: "hello2"
+                      }
+                    }
+                  },
+                  schema: {
+                    $ref: "#/components/schemas/MyModel"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/examples.ts

@@ -0,0 +1,20 @@
+import {OpenSpecHash, OpenSpecRef, OS3Example} from "@tsed/openspec";
+
+import {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Add a examples metadata on the decorated element.
+ *
+ * @decorator
+ * @swagger
+ * @schema
+ * @input
+ * @methodDecorator
+ * @classDecorator
+ */
+export function Examples(examples: OpenSpecHash<OS3Example | OpenSpecRef>): ParameterDecorator {
+  return JsonEntityFn((store: JsonParameterStore) => {
+    store.parameter!.examples(examples);
+  });
+}

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

@@ -0,0 +1,47 @@
+import "../../index.js";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {ExclusiveMaximum} from "./exclusiveMaximum.js";
+
+describe("@ExclusiveMaximum", () => {
+  it("should declare exclusiveMaximum value", () => {
+    // WHEN
+    class Model {
+      @ExclusiveMaximum(0, true)
+      num: number;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          exclusiveMaximum: 0,
+          type: "number"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare exclusiveMaximum value (default value)", () => {
+    // WHEN
+    class Model {
+      @ExclusiveMaximum(0)
+      num: number;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          exclusiveMaximum: 0,
+          type: "number"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/exclusiveMaximum.ts

@@ -0,0 +1,75 @@
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {Maximum} from "./maximum.js";
+
+/**
+ * The value of `exclusiveMaximum` MUST be number, representing an exclusive upper limit for a numeric instance.
+ *
+ * If the instance is a number, then the instance is valid only if it has a value strictly less than (not equal to) `exclusiveMaximum`.
+ *
+ * ::: warning
+ * For v6 user, use @@ExclusiveMaximum@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ * ### With primitive type
+ *
+ * ```typescript
+ * class Model {
+ *    @ExclusiveMaximum(10)
+ *    property: number;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "number",
+ *       "exclusiveMaximum": 10
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With array type
+ *
+ * ```typescript
+ * class Model {
+ *    @ExclusiveMaximum(10)
+ *    @CollectionOf(Number)
+ *    property: number[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "array",
+ *       "items": {
+ *          "type": "number",
+ *          "exclusiveMaximum": 10
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param maximum
+ * @param {boolean} exclusiveMaximum
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @ajv-errors
+ */
+export const ExclusiveMaximum = withErrorMsg("exclusiveMaximum", (maximum: number, exclusiveMaximum: boolean = true) => {
+  return Maximum(maximum, exclusiveMaximum);
+});

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

@@ -0,0 +1,47 @@
+import "../../index.js";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {ExclusiveMinimum} from "./exclusiveMinimum.js";
+
+describe("@ExclusiveMinimum", () => {
+  it("should declare exclusiveMinimum value", () => {
+    // WHEN
+    class Model {
+      @ExclusiveMinimum(0, true)
+      num: number;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          exclusiveMinimum: 0,
+          type: "number"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare exclusiveMinimum value (default value)", () => {
+    // WHEN
+    class Model {
+      @ExclusiveMinimum(0)
+      num: number;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          exclusiveMinimum: 0,
+          type: "number"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/exclusiveMinimum.ts

@@ -0,0 +1,75 @@
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {Minimum} from "./minimum.js";
+
+/**
+ * The value of `exclusiveMinimum` MUST be number, representing an exclusive upper limit for a numeric instance.
+ *
+ * If the instance is a number, then the instance is valid only if it has a value strictly greater than (not equal to) `exclusiveMinimum`.
+ *
+ * ::: warning
+ * For v6 user, use @@ExclusiveMinimum@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ * ### With primitive type
+ *
+ * ```typescript
+ * class Model {
+ *    @ExclusiveMinimum(10)
+ *    property: number;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "number",
+ *       "exclusiveMinimum": 10
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With array type
+ *
+ * ```typescript
+ * class Model {
+ *    @ExclusiveMinimum(10)
+ *    @CollectionOf(Number)
+ *    property: number[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "array",
+ *       "items": {
+ *          "type": "number",
+ *          "exclusiveMinimum": 10
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param minimum
+ * @param {boolean} exclusiveMinimum
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @ajv-errors
+ */
+export const ExclusiveMinimum = withErrorMsg("exclusiveMinimum", (minimum: number, exclusiveMinimum: boolean = true) => {
+  return Minimum(minimum, exclusiveMinimum);
+});

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

@@ -0,0 +1,149 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {DateFormat, DateTime, Email, Format, TimeFormat, Uri, Url} from "./format.js";
+
+describe("@Format", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Format("email")
+      email: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        email: {
+          format: "email",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@Email", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Email()
+      email: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        email: {
+          format: "email",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@DateFormat", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @DateFormat()
+      prop: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          format: "date",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@TimeFormat", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @TimeFormat()
+      prop: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          format: "time",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@DateTime", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @DateTime()
+      prop: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          format: "date-time",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@Uri", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Uri()
+      prop: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          format: "uri",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@Url", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Url()
+      prop: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          format: "url",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});