@tsed/schema 8.0.0 → 8.0.2

package/src/decorators/common/groups.ts

@@ -0,0 +1,66 @@
+import {DecoratorTypes, isArray} from "@tsed/core";
+
+import type {JsonClassStore} from "../../domain/JsonClassStore.js";
+import type {JsonParameterStore} from "../../domain/JsonParameterStore.js";
+import {matchGroups} from "../../utils/matchGroups.js";
+import {CustomKey} from "./customKey.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * @ignore
+ */
+function groupsClass(groups: any, entity: JsonClassStore) {
+  const entries: [string, string[]][] = Object.entries(groups[0]);
+
+  entity.children.forEach((propEntity) => {
+    const groups = entries.filter(([, props]) => props.includes(propEntity.propertyName)).map(([key]) => key);
+    const decorator: any = Groups(...groups);
+
+    decorator(propEntity.target, propEntity.propertyKey);
+  });
+}
+
+/**
+ * Apply groups validation strategy
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Groups<T>(groupsDefinition: Record<string, (keyof T)[]>): ClassDecorator;
+export function Groups<T>(groupName: string, groups: string[]): ParameterDecorator;
+export function Groups(...groups: string[]): Function;
+export function Groups(...groups: any): any {
+  return JsonEntityFn((entity) => {
+    switch (entity.decoratorType) {
+      case DecoratorTypes.CLASS:
+        groupsClass(groups, entity as JsonClassStore);
+        break;
+      case DecoratorTypes.PROP:
+        CustomKey("x-groups", groups)(entity.target, entity.propertyKey);
+        entity.schema.$hooks.on("groups", (prev: boolean, givenGroups: string[]) => {
+          if (!prev) {
+            if (matchGroups(groups, givenGroups)) {
+              return true;
+            }
+          }
+
+          return prev;
+        });
+        break;
+      case DecoratorTypes.PARAM:
+        let groupsName = "";
+
+        if (groups.length == 2 && isArray(groups[1])) {
+          groupsName = groups[0];
+          groups = groups[1];
+        }
+
+        (entity as JsonParameterStore).parameter.groups = groups;
+        (entity as JsonParameterStore).parameter.groupsName = groupsName;
+        break;
+    }
+  });
+}

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

@@ -0,0 +1,52 @@
+import {Get, getSpec, Path, SpecTypes} from "../../index.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Hidden} from "./hidden.js";
+
+describe("@Hidden", () => {
+  it("should generate the right json schema", () => {
+    // WHEN
+    class Model {
+      @Hidden()
+      prop: number;
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      type: "object"
+    });
+  });
+
+  it("should generate the right json schema (2)", () => {
+    // WHEN
+    @Path("/")
+    class Model {
+      @Hidden()
+      @Get("/hidden")
+      hidden() {}
+
+      @Get("/hidden")
+      method() {}
+    }
+
+    expect(getSpec(Model, {specType: SpecTypes.OPENAPI})).toEqual({
+      paths: {
+        "/hidden": {
+          get: {
+            operationId: "modelMethod",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["Model"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "Model"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/common/hidden.ts

@@ -0,0 +1,36 @@
+import {StoreSet} from "@tsed/core";
+
+/**
+ * Disable documentation for the class and his endpoint.
+ *
+ * ````typescript
+ * @Controller('/')
+ * export class Ctrl {
+ *
+ *   @Get('/')
+ *   @Hidden()
+ *   hiddenRoute(){
+ *
+ *   }
+ * }
+ *
+ * @Controller('/')
+ * @Hidden()
+ * export class Ctrl {
+ *   @Get('/')
+ *   hiddenRoute() {
+ *
+ *   }
+ *   @Get('/2')
+ *   hiddenRoute2() {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * @decorator
+ * @ignore
+ */
+export function Hidden() {
+  return StoreSet("hidden", true);
+}

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

@@ -0,0 +1,88 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Ignore} from "./ignore.js";
+import {Property} from "./property.js";
+
+describe("@Ignore", () => {
+  it("should declare prop", () => {
+    // WHEN
+    class Model {
+      @Ignore()
+      prop1: string;
+
+      @Property()
+      prop2: string;
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop2: {
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should declare prop (boolean)", () => {
+    // WHEN
+    class Model {
+      @Ignore(true)
+      prop1: string;
+
+      @Property()
+      prop2: string;
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop2: {
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should declare prop (with callback)", () => {
+    // WHEN
+    class Model {
+      @Ignore((value, ctx) => !ctx.endpoint)
+      prop1: string;
+
+      @Property()
+      prop2: string;
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop1: {
+          type: "string"
+        },
+        prop2: {
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should ignore prop (with callback)", () => {
+    // WHEN
+    class Model {
+      @Ignore((value, ctx) => ctx.endpoint)
+      prop1: string;
+
+      @Property()
+      prop2: string;
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop2: {
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/ignore.ts

@@ -0,0 +1,66 @@
+import {IgnoreCallback} from "../../interfaces/IgnoreCallback.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Ignore the property when JsonMapper serialize the class to a Plain Object JavaScript.
+ *
+ * ::: warning
+ * Swagger will not generate documentation for the ignored property.
+ * :::
+ *
+ * ```typescript
+ * class User {
+ *   @Ignore()
+ *   _id: string;
+ *
+ *   @Property()
+ *   firstName: string;
+ *
+ *   @Property()
+ *   lastName: string;
+ *
+ *   @Ignore((value, ctx) => !ctx.endpoint)
+ *   password: string;
+ * }
+ * ```
+ *
+ * The controller:
+ * ```typescript
+ * import {Controller, BodyParams} from "@tsed/platform-http";
+ * import {Post} from "@tsed/schema";
+ * import {Person} from "../models/Person.js";
+ *
+ * @Controller("/")
+ * export class UsersCtrl {
+ *   @Get("/")
+ *   get(): User {
+ *     const user = new User();
+ *     user._id = "12345";
+ *     user.firstName = "John";
+ *     user.lastName = "Doe";
+ *     user.password = "secretpassword";
+ *     return
+ *   }
+ * }
+ * ```
+ *
+ * The expected json object:
+ *
+ * ```json
+ * {
+ *  "firstName": "John",
+ *  "lastName": "Doe"
+ * }
+ * ```
+ * @param cb Callback to know if the property must be ignored
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @deprecated Since v7. Use @Groups decorator instead of and enable `jsonMapper.strictGroups` in your configuration.
+ */
+export function Ignore(cb: boolean | IgnoreCallback = true) {
+  return JsonEntityFn((store) => {
+    store.schema.ignore(cb);
+  });
+}

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

@@ -0,0 +1,110 @@
+import {BodyParams} from "@tsed/platform-params";
+
+import {validateSpec} from "../../../test/helpers/validateSpec.js";
+import {SpecTypes} from "../../domain/SpecTypes.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {getSpec} from "../../utils/getSpec.js";
+import {OperationPath} from "../operations/operationPath.js";
+import {Path} from "../operations/path.js";
+import {Returns} from "../operations/returns.js";
+import {Integer} from "./integer.js";
+
+describe("@Integer", () => {
+  it("should generate the right json schema", () => {
+    // WHEN
+    class Model {
+      @Integer()
+      prop: number;
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          multipleOf: 1,
+          type: "integer"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should generate the right json schema (array)", () => {
+    // WHEN
+    class Model {
+      @Integer()
+      prop: number[];
+    }
+
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          items: {
+            multipleOf: 1,
+            type: "integer"
+          },
+          type: "array"
+        }
+      },
+      type: "object"
+    });
+  });
+
+  it("should generate the OS3", async () => {
+    @Path("/")
+    class TestIntegerCtrl {
+      @OperationPath("GET", "/")
+      @(Returns(200, Array).OfInteger())
+      async get(@BodyParams() @Integer() number: number[]) {}
+    }
+
+    const spec = getSpec(TestIntegerCtrl, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "testIntegerCtrlGet",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    items: {
+                      multipleOf: 1,
+                      type: "integer"
+                    },
+                    type: "array"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: {
+                      items: {
+                        multipleOf: 1,
+                        type: "integer"
+                      },
+                      type: "array"
+                    }
+                  }
+                },
+                description: "Success"
+              }
+            },
+            tags: ["TestIntegerCtrl"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "TestIntegerCtrl"
+        }
+      ]
+    });
+    expect(await validateSpec(spec, SpecTypes.OPENAPI)).toBe(true);
+  });
+});

package/src/decorators/common/integer.ts

@@ -0,0 +1,69 @@
+import type {JSONSchema6} from "json-schema";
+
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * Set integer type.
+ *
+ * ::: warning
+ * For v6 user, use @@Integer@@ from @tsed/schema instead of @@Integer@@ from @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Integer()
+ *    property: number;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "integer"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With array of multiple types
+ *
+ * ```typescript
+ * class Model {
+ *    @Integer()
+ *    property: number[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "array",
+ *       "items": {
+ *          "type": "integer"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export function Integer() {
+  return JsonEntityFn((store) => {
+    store.itemSchema.type("integer");
+  });
+}

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

@@ -0,0 +1,16 @@
+import {JsonEntityFn} from "../../index.js";
+
+describe("JsonSchemaStoreFn", () => {
+  it("should decorate property", () => {
+    const stub = vi.fn();
+
+    class Model {
+      @JsonEntityFn(() => {
+        return stub;
+      })
+      prop: string;
+    }
+
+    expect(stub).toHaveBeenCalledWith(Model.prototype, "prop", undefined);
+  });
+});

package/src/decorators/common/jsonEntityFn.ts

@@ -0,0 +1,33 @@
+import {DecoratorParameters} from "@tsed/core";
+
+import type {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {getJsonEntityStore} from "../../utils/getJsonEntityStore.js";
+
+/**
+ * Decorator util to compose another decorator. See @@Description@@ decorator implementation for more details.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * export function Description(description: any) {
+ *   return JsonEntityFn((entity: JsonEntityStore, args: DecoratorParameters) => {
+ *       entity.itemSchema.description(description)
+ *   });
+ * }
+ * ```
+ *
+ * @param fn
+ * @decorator
+ * @utils
+ * @model
+ */
+export function JsonEntityFn<T extends JsonEntityStore = JsonEntityStore>(
+  fn: (entity: T, parameters: DecoratorParameters) => any
+): (...args: any[]) => any {
+  return (...parameters: DecoratorParameters) => {
+    const result: any = fn(getJsonEntityStore<T>(...parameters) as T, parameters);
+    if (typeof result === "function") {
+      result(...parameters);
+    }
+  };
+}

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

@@ -0,0 +1,61 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {CollectionOf} from "../collections/collectionOf.js";
+import {MaxLength} from "./maxLength.js";
+
+describe("@MaxLength", () => {
+  it("should declare minimum value", () => {
+    // WHEN
+    class Model {
+      @MaxLength(0)
+      word: string;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        word: {
+          maxLength: 0,
+          type: "string"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should throw error", () => {
+    // WHEN
+    let actualError: any;
+    try {
+      MaxLength(-1);
+    } catch (er) {
+      actualError = er;
+    }
+
+    // THEN
+    expect(actualError.message).toBe("The value of maxLength MUST be a non-negative integer.");
+  });
+  it("should declare minimum value (collection)", () => {
+    // WHEN
+    class Model {
+      @MaxLength(0)
+      @CollectionOf(String)
+      words: string[];
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        words: {
+          type: "array",
+          items: {
+            maxLength: 0,
+            type: "string"
+          }
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/common/maxLength.ts

@@ -0,0 +1,88 @@
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {JsonEntityFn} from "./jsonEntityFn.js";
+
+/**
+ * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword.
+ *
+ * The length of a string instance is defined as the number of its characters as defined by [RFC 7159](http://json-schema.org/latest/json-schema-validation.html#RFC7159).
+ *
+ * ::: warning
+ * The value of maxLength MUST be a non-negative integer.
+ * :::
+ *
+ * ::: tip
+ * Omitting this keyword has the same behavior as a value of 0.
+ * :::
+ *
+ * ::: warning
+ * For v6 user, use @@MaxLength@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ * ### With primitive type
+ *
+ * ```typescript
+ * class Model {
+ *    @MaxLength(10)
+ *    property: number;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "string",
+ *       "maxLength": 10
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### With array type
+ *
+ * ```typescript
+ * class Model {
+ *    @MaxLength(10)
+ *    @CollectionOf(String)
+ *    property: string[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "array",
+ *       "items": {
+ *          "type": "string",
+ *          "maxLength": 10
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {number} maxLength The maximum length allowed
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @ajv-errors
+ */
+export const MaxLength = withErrorMsg("maxLength", (maxLength: number) => {
+  if (maxLength < 0) {
+    throw new Error("The value of maxLength MUST be a non-negative integer.");
+  }
+
+  return JsonEntityFn((store) => {
+    store.itemSchema.maxLength(maxLength);
+  });
+});