@tsed/schema 8.0.1 → 8.0.3

package/src/decorators/common/nullable.ts

@@ -0,0 +1,32 @@
+import {Type, useDecorators} from "@tsed/core";
+import type {JSONSchema6TypeName} from "json-schema";
+
+import {Any} from "./any.js";
+import {Property} from "./property.js";
+
+/**
+ * Set field as nullable.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Nullable(Date)
+ *    property: Date | null;
+ *
+ *    @Nullable(String, Number, Boolean)
+ *    property: string | number | boolean | null;
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Nullable(type: JSONSchema6TypeName | Type<any> | any, ...types: (JSONSchema6TypeName | Type<any> | any)[]) {
+  types = [type, ...types];
+  return useDecorators(types.length === 1 && Property(types[0]), Any(null, ...types));
+}

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

@@ -0,0 +1,301 @@
+import {AllOf, getJsonSchema, getSpec, In, OneOf, OperationPath, Path, Property, SpecTypes} from "../../index.js";
+import {number, string} from "../../utils/from.js";
+
+describe("@OneOf", () => {
+  it("should declare return schema", () => {
+    // WHEN
+    class Model {
+      @OneOf(string(), number())
+      num: string;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      properties: {
+        num: {
+          oneOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "number"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare return schema for only one model", () => {
+    // WHEN
+    class Nested {
+      @Property()
+      id: string;
+    }
+    class Model {
+      @OneOf(Nested)
+      num: string;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      definitions: {
+        Nested: {
+          properties: {
+            id: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      properties: {
+        num: {
+          $ref: "#/definitions/Nested"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare two models", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @OneOf(One1, One2)
+      test: One1 | One2;
+    }
+
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      definitions: {
+        One1: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            }
+          }
+        },
+        One2: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            }
+          }
+        }
+      },
+      properties: {
+        test: {
+          oneOf: [
+            {
+              $ref: "#/definitions/One1"
+            },
+            {
+              $ref: "#/definitions/One2"
+            }
+          ]
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare two models - OS3", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @OneOf(One1, One2)
+      test: One1 | One2;
+    }
+
+    @Path("/")
+    class MyController {
+      @OperationPath("POST", "/")
+      get(@In("body") payload: Model) {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              test: {
+                oneOf: [
+                  {
+                    $ref: "#/components/schemas/One1"
+                  },
+                  {
+                    $ref: "#/components/schemas/One2"
+                  }
+                ]
+              }
+            },
+            type: "object"
+          },
+          One1: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          },
+          One2: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Model"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should declare two models (array) - OS3", () => {
+    class One1 {
+      @Property()
+      id: string;
+    }
+
+    class One2 {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @OneOf(One1, One2)
+      list: (One1 | One2)[];
+    }
+
+    @Path("/")
+    class MyController {
+      @OperationPath("POST", "/")
+      get(@In("body") payload: Model) {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      components: {
+        schemas: {
+          Model: {
+            properties: {
+              list: {
+                type: "array",
+                items: {
+                  oneOf: [
+                    {
+                      $ref: "#/components/schemas/One1"
+                    },
+                    {
+                      $ref: "#/components/schemas/One2"
+                    }
+                  ]
+                }
+              }
+            },
+            type: "object"
+          },
+          One1: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          },
+          One2: {
+            properties: {
+              id: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Model"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/oneOf.ts

@@ -0,0 +1,24 @@
+import {AnyJsonSchema} from "../../domain/JsonSchema.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * See https://tools.ietf.org/html/draft-wright-json-schema-validation-01#section-6.28
+ *
+ * ::: warning
+ * OneOf isn't supported by OS2
+ * :::
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ * @param oneOf
+ */
+export function OneOf(...oneOf: AnyJsonSchema[]) {
+  return JsonEntityFn((entity) => {
+    entity.itemSchema.oneOf(oneOf);
+    entity.type = Object;
+  });
+}

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

@@ -0,0 +1,43 @@
+import {getSpec, In, Name, OperationPath, Optional, SpecTypes} from "../../index.js";
+import {Path} from "../operations/path.js";
+
+describe("Optional", () => {
+  it("should set metadata when optional is used on param", () => {
+    @Path("/")
+    class MyController {
+      @OperationPath("GET", "/")
+      method(@In("query") @Name("q") @Optional() q: string) {}
+    }
+
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerMethod",
+            parameters: [
+              {
+                in: "query",
+                name: "q",
+                required: false,
+                schema: {
+                  type: "string"
+                }
+              }
+            ],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/optional.ts

@@ -0,0 +1,26 @@
+import {DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import type {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Add optional annotation on Property or Parameter.
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Optional() {
+  return JsonEntityFn((store) => {
+    switch (store.decoratorType) {
+      case DecoratorTypes.PARAM:
+        (store as JsonParameterStore).required = false;
+        break;
+      case DecoratorTypes.PROP:
+        store.parentSchema.removeRequired(store.propertyName);
+        break;
+    }
+  });
+}

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

@@ -0,0 +1,27 @@
+import "../../index.js";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {Pattern} from "./pattern.js";
+
+describe("@Pattern", () => {
+  it("should declare pattern value", () => {
+    // WHEN
+    class Model {
+      @Pattern(/(a|b)/)
+      num: string;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          pattern: "(a|b)",
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/pattern.ts

@@ -0,0 +1,102 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * The pattern and Pattern Properties keywords use regular expressions to express constraints.
+ * The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that complete syntax is not widely supported, therefore it is recommended that you stick to the subset of that syntax described below.
+ *
+ * ::: warning
+ * For v6 user, use @@Pattern@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * A single unicode character (other than the special characters below) matches itself.
+ *
+ * * `^`: Matches only at the beginning of the string.
+ * * `$`: Matches only at the end of the string.
+ * * `(...)`: Group a series of regular expressions into a single regular expression.
+ * * `|`: Matches either the regular expression preceding or following the | symbol.
+ * * `[abc]`: Matches any of the characters inside the square brackets.
+ * * `[a-z]`: Matches the range of characters.
+ * * `[^abc]`: Matches any character not listed.
+ * * `[^a-z]`: Matches any character outside of the range.
+ * * `+`: Matches one or more repetitions of the preceding regular expression.
+ * * `*`: Matches zero or more repetitions of the preceding regular expression.
+ * * `?`: Matches zero or one repetitions of the preceding regular expression.
+ * * `+?`, *?`, ??`: The `*`, `+`, and `?` qualifiers are all greedy; they match as much text as possible. Sometimes this behavior isn’t desired and you want to match as few characters as possible.
+ * * `{x}`: Match exactly x occurrences of the preceding regular expression.
+ * * `{x,y}`: Match at least x and at most y occurrences of the preceding regular expression.
+ * * `{x,}`: Match x occurrences or more of the preceding regular expression.
+ * * `{x}?`, {x,y}?, {x,}?`: Lazy versions of the above expressions.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Pattern("^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$")
+ *    @Pattern(/^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$/)
+ *    property: string;
+ * }
+ * ```
+ *
+ * ### With primitive type
+ *
+ * ```typescript
+ * class Model {
+ *    @Pattern(/^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$/)
+ *    property: string;
+ * }
+ * ```
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "string",
+ *       "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With array type
+ *
+ * ```typescript
+ * class Model {
+ *    @CollectionOf(string)
+ *    @Pattern(/^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$/)
+ *    property: string[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "array",
+ *       "items": {
+ *         "type": "string",
+ *         "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {string} pattern
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @ajv-errors
+ */
+export const Pattern = withErrorMsg("pattern", (pattern: string | RegExp) => {
+  return JsonEntityFn((store: JsonEntityStore) => {
+    store.itemSchema.pattern(pattern);
+  });
+});

package/src/decorators/common/property.ts

@@ -0,0 +1,24 @@
+import {isArrowFn, isClass} from "@tsed/core";
+
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Declare a new property on a model.
+ *
+ * @param type
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Property(type?: any) {
+  return JsonEntityFn((store) => {
+    if (type) {
+      if (isClass(type) || isArrowFn(type)) {
+        store.type = type;
+      }
+      store.itemSchema.type(type);
+    }
+  });
+}

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

@@ -0,0 +1,135 @@
+import {Format, getJsonSchema, getSpec, In, Path, Post, Property, Returns, SpecTypes} from "../../index.js";
+import {ReadOnly} from "./readOnly.js";
+
+describe("@ReadOnly", () => {
+  it("should declare readOnly field", () => {
+    // WHEN
+    class Model {
+      @ReadOnly(true)
+      num: string;
+    }
+
+    // THEN
+    const schema = getJsonSchema(Model);
+
+    expect(schema).toEqual({
+      properties: {
+        num: {
+          readOnly: true,
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should declare property as readonly (OS3)", () => {
+    class TestPerson {
+      @Property()
+      name: string;
+
+      @Property()
+      band: string;
+    }
+
+    // WHEN
+    class TestBand {
+      @Format("date-time")
+      @ReadOnly()
+      createdAt: number = Date.now();
+
+      @Format("date-time")
+      @ReadOnly()
+      updatedAt: number = Date.now();
+
+      @ReadOnly()
+      @Property(TestPerson)
+      members: TestPerson;
+    }
+
+    @Path("/")
+    class MyCtrl {
+      @Post("/")
+      @Returns(200, TestBand)
+      post(@In("body") model: TestBand) {}
+    }
+
+    // THEN
+    expect(getSpec(MyCtrl, {specType: SpecTypes.OPENAPI})).toEqual({
+      components: {
+        schemas: {
+          TestBand: {
+            properties: {
+              createdAt: {
+                format: "date-time",
+                readOnly: true,
+                type: "number"
+              },
+              members: {
+                anyOf: [
+                  {
+                    $ref: "#/components/schemas/TestPerson"
+                  }
+                ],
+                readOnly: true
+              },
+              updatedAt: {
+                format: "date-time",
+                readOnly: true,
+                type: "number"
+              }
+            },
+            type: "object"
+          },
+          TestPerson: {
+            properties: {
+              band: {
+                type: "string"
+              },
+              name: {
+                type: "string"
+              }
+            },
+            type: "object"
+          }
+        }
+      },
+      paths: {
+        "/": {
+          post: {
+            operationId: "myCtrlPost",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/TestBand"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/TestBand"
+                    }
+                  }
+                },
+                description: "Success"
+              }
+            },
+            tags: ["MyCtrl"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyCtrl"
+        }
+      ]
+    });
+  });
+});