@tsed/schema 8.0.1 → 8.0.3

package/src/decorators/collections/collectionOf.spec.ts

@@ -0,0 +1,327 @@
+import {catchError} from "@tsed/core";
+
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {array, map, string} from "../../utils/from.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {Property} from "../common/property.js";
+import {Schema} from "../common/schema.js";
+import {In} from "../operations/in.js";
+import {OperationPath} from "../operations/operationPath.js";
+import {CollectionContains} from "./collectionContains.js";
+import {ArrayOf, CollectionOf, MapOf} from "./collectionOf.js";
+import {MaxItems} from "./maxItems.js";
+import {MinItems} from "./minItems.js";
+
+describe("@CollectionOf", () => {
+  it("should declare a collection and catch error (Array of)", () => {
+    // WHEN
+    const error = catchError(() => {
+      class Model {
+        @CollectionOf(undefined)
+        num: number[];
+      }
+    });
+
+    expect(error?.message).toEqual(
+      "A type is required on `@CollectionOf(type)` decorator. Please give a type or wrap it inside an arrow function if you have a circular reference."
+    );
+  });
+  it("should declare an array of map of string", () => {
+    const schema = array().items(map().additionalProperties(string()));
+
+    class Test {
+      @Schema(schema)
+      @CollectionOf(Map)
+      fields: Map<string, string>[] = [];
+    }
+
+    expect(getJsonSchema(Test)).toEqual({
+      properties: {
+        fields: {
+          items: {
+            additionalProperties: {
+              type: "string"
+            },
+            type: "object"
+          },
+          type: "array"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare a collection (Array of)", () => {
+    // WHEN
+    class Model {
+      @CollectionOf(Number)
+      num: number[];
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          items: {
+            type: "number"
+          },
+          type: "array"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare a collection (Array of Model)", () => {
+    // WHEN
+    class Nested {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @MaxItems(10)
+      @CollectionOf(Nested)
+      @MinItems(1)
+      prop: Nested[];
+    }
+
+    // THEN
+    const entity = JsonEntityStore.from(Model, "prop");
+    const schema = getJsonSchema(Model);
+
+    expect(entity.schema.getTarget()).toEqual(Array);
+    expect(entity.schema.get("type")).toEqual("array");
+    expect(entity.itemSchema.getComputedType()).toEqual(Nested);
+
+    expect(schema).toEqual({
+      definitions: {
+        Nested: {
+          properties: {
+            id: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      properties: {
+        prop: {
+          items: {
+            $ref: "#/definitions/Nested"
+          },
+          minItems: 1,
+          maxItems: 10,
+          type: "array"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare a collection (Array of Model on param)", () => {
+    // WHEN
+    class Nested {
+      @Property()
+      id: string;
+    }
+
+    class Model {
+      @Property()
+      id: string;
+      @CollectionOf(Nested)
+      prop: Nested;
+    }
+
+    class Ctrl {
+      @OperationPath("POST", "/")
+      test(@In("body") @CollectionOf(Model) body: Model[]) {}
+    }
+
+    // THEN
+    const entity = JsonEntityStore.from(Ctrl.prototype, "test", 0);
+
+    expect(getJsonSchema(entity)).toEqual({
+      definitions: {
+        Model: {
+          properties: {
+            id: {
+              type: "string"
+            },
+            prop: {
+              $ref: "#/definitions/Nested"
+            }
+          },
+          type: "object"
+        },
+        Nested: {
+          properties: {
+            id: {
+              type: "string"
+            }
+          },
+          type: "object"
+        }
+      },
+      items: {
+        $ref: "#/definitions/Model"
+      },
+      type: "array"
+    });
+  });
+  it("should declare a collection (Map of)", () => {
+    // WHEN
+    class Model {
+      @(CollectionOf(Number).MinProperties(2).MaxProperties(5))
+      num: Map<string, number>;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          additionalProperties: {
+            type: "number"
+          },
+          maxProperties: 5,
+          minProperties: 2,
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare a collection (Set of)", () => {
+    // WHEN
+    class Model {
+      @CollectionOf(Number)
+      num: Set<number>;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          items: {
+            type: "number"
+          },
+          type: "array",
+          uniqueItems: true
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare collection with additional props", () => {
+    // WHEN
+    class Model {
+      @(CollectionOf(String).MinItems(0).MaxItems(10).UniqueItems())
+      words: string[];
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        words: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          maxItems: 10,
+          minItems: 0,
+          uniqueItems: true
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare collection with additional props and contains", () => {
+    // WHEN
+    class Model {
+      @(CollectionContains(String).MinItems(0).MaxItems(10))
+      words: string[];
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        words: {
+          type: "array",
+          contains: {
+            type: "string"
+          },
+          maxItems: 10,
+          minItems: 0
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@ArrayOf", () => {
+  interface ArrayList<T> extends Array<T> {
+    pull(query: any): this;
+  }
+
+  it("should declare a collection (Array of)", () => {
+    // WHEN
+    class Model {
+      @ArrayOf(Number)
+      num: ArrayList<number>;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          items: {
+            type: "number"
+          },
+          type: "array"
+        }
+      },
+      type: "object"
+    });
+  });
+});
+
+describe("@MapOf", () => {
+  interface MapCollection<K, V> extends Map<K, V> {
+    take(query: any): V;
+  }
+
+  it("should declare a collection (Map of)", () => {
+    // WHEN
+    class Model {
+      @(MapOf(Number).MinProperties(2).MaxProperties(5))
+      num: MapCollection<string, number>;
+    }
+
+    // THEN
+    const classSchema = JsonEntityStore.from(Model);
+
+    expect(classSchema.schema.toJSON()).toEqual({
+      properties: {
+        num: {
+          additionalProperties: {
+            type: "number"
+          },
+          maxProperties: 5,
+          minProperties: 2,
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+});

package/src/decorators/collections/collectionOf.ts

@@ -0,0 +1,182 @@
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+
+export interface ArrayOfChainedDecorators {
+  (...args: any): any;
+
+  /**
+   * An array instance is valid against `minItems` if its size is greater than, or equal to, the value of this keyword.
+   *
+   * ::: warning
+   * The value `minItems` MUST be a non-negative integer.
+   * :::
+   *
+   * ::: tip
+   * Omitting this keyword has the same behavior as a value of 0.
+   * :::
+   */
+  MinItems(minItems: number): this;
+
+  /**
+   * The value `maxItems` MUST be a non-negative integer.
+   *
+   * An array instance is valid against `maxItems` if its size is less than, or equal to, the value of this keyword.
+   *
+   * :: warning
+   * The value `maxItems` MUST be a non-negative integer.
+   * :::
+   */
+  MaxItems(maxItems: number): this;
+
+  /**
+   * Set the type of the item collection. The possible value is String, Boolean, Number, Date, Object, Class, etc...
+   *
+   * The array instance will be valid against "contains" if at least one of its elements is valid against the given schema.
+   */
+  Contains(): this;
+
+  /**
+   * If this keyword has boolean value false, the instance validates successfully. If it has boolean value true, the instance validates successfully if all of its elements are unique.
+   */
+  UniqueItems(uniqueItems?: boolean): this;
+}
+
+export interface MapOfChainedDecorators {
+  (...args: any): any;
+
+  /**
+   * An object instance is valid against `minProperties` if its number of properties is less than, or equal to, the value of this keyword.
+   *
+   * ::: warning
+   * The value of this keyword MUST be a non-negative integer.
+   * :::
+   */
+  MinProperties(minProperties: number): this;
+
+  /**
+   * An object instance is valid against `maxProperties` if its number of properties is less than, or equal to, the value of this keyword.
+   *
+   * ::: warning
+   * The value of this keyword MUST be a non-negative integer.
+   * :::
+   */
+  MaxProperties(maxProperties: number): this;
+}
+
+export interface CollectionOfChainedDecorators extends MapOfChainedDecorators, ArrayOfChainedDecorators {}
+
+/**
+ * Set the type of the item collection. The possible value is String, Boolean, Number, Date, Object, Class, etc...
+ *
+ * ```typescript
+ * class Model {
+ *    @CollectionOf(String).MinLength(0).MaxLength(0)
+ *    property: string[];
+ * }
+ * ```
+ * ::: warning
+ * You mustn't use the `type Type = string | number` as parameters Type.
+ *
+ * This example doesn't work:
+ *
+ * ```typescript
+ * type Type = "string" | "number"
+ * class Model {
+ *    @CollectionOf(Type)
+ *    property: Type[];
+ * }
+ * ```
+ * :::
+ *
+ * @param {Type<any>} type
+ * @param collectionType
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @collections
+ */
+export function CollectionOf(type: any, collectionType?: any): CollectionOfChainedDecorators {
+  if (!type) {
+    throw new Error(
+      "A type is required on `@CollectionOf(type)` decorator. Please give a type or wrap it inside an arrow function if you have a circular reference."
+    );
+  }
+
+  const schema: any = {};
+  let contains: boolean = false;
+
+  const decorator = (...args: any) => {
+    const store = JsonEntityStore.from(...args);
+
+    if (collectionType) {
+      store.collectionType = collectionType;
+      store.schema.type(collectionType);
+    }
+
+    store.type = type;
+    store.itemSchema.type(type);
+
+    store.schema.assign(schema);
+
+    if (store.isArray && contains) {
+      store.schema.set("contains", store.schema.get("items"));
+      store.schema.delete("items");
+    }
+  };
+
+  decorator.MinItems = (minItems: number) => {
+    schema.minItems = minItems;
+
+    return decorator;
+  };
+
+  decorator.MaxItems = (maxItems: number) => {
+    schema.maxItems = maxItems;
+
+    return decorator;
+  };
+  decorator.MinProperties = (minProperties: number) => {
+    schema.minProperties = minProperties;
+
+    return decorator;
+  };
+
+  decorator.MaxProperties = (maxProperties: number) => {
+    schema.maxProperties = maxProperties;
+
+    return decorator;
+  };
+
+  decorator.Contains = () => {
+    contains = true;
+
+    return decorator;
+  };
+
+  decorator.UniqueItems = (uniqueItems = true) => {
+    schema.uniqueItems = uniqueItems;
+
+    return decorator;
+  };
+
+  return decorator;
+}
+
+/**
+ * Alias of @@GenericOf@@ decorator.
+ * @param type
+ * @decorator
+ */
+export function ArrayOf(type: any): ArrayOfChainedDecorators {
+  return CollectionOf(type, Array);
+}
+
+/**
+ * Alias of @@GenericOf@@ decorator.
+ * @param type
+ * @decorator
+ */
+export function MapOf(type: any): MapOfChainedDecorators {
+  return CollectionOf(type, Map);
+}

package/src/decorators/collections/maxItems.spec.ts

@@ -0,0 +1,40 @@
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {CollectionOf} from "./collectionOf.js";
+import {MaxItems} from "./maxItems.js";
+
+describe("@MaxItems", () => {
+  it("should declare a prop", () => {
+    // WHEN
+    class Model {
+      @CollectionOf(Number)
+      @MaxItems(10)
+      num: number[];
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        num: {
+          items: {
+            type: "number"
+          },
+          maxItems: 10,
+          type: "array"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should throw error", () => {
+    // WHEN
+    let actualError: any;
+    try {
+      MaxItems(-1);
+    } catch (er) {
+      actualError = er;
+    }
+
+    // THEN
+    expect(actualError.message).toBe("The value of maxItems MUST be a non-negative integer.");
+  });
+});

package/src/decorators/collections/maxItems.ts

@@ -0,0 +1,59 @@
+import {withErrorMsg} from "../../utils/withErrorMsg.js";
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * The value `maxItems` MUST be a non-negative integer.
+ *
+ * An array instance is valid against `maxItems` if its size is less than, or equal to, the value of this keyword.
+ *
+ * :: warning
+ * The value `maxItems` MUST be a non-negative integer.
+ * :::
+ *
+ * :: warning
+ * This decorator will be removed in v7.
+ * For v6 user, use @@MaxItems@@ from @tsed/schema instead of @tsed/platform-http.
+ * :::
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @CollectionOf(String)
+ *    @MaxItems(10)
+ *    property: string[];
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "property": {
+ *       "type": "number",
+ *       "maxItems": 10
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {number} maxItems
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @collections
+ * @ajv-errors
+ */
+export const MaxItems = withErrorMsg("maxItems", (maxItems: number) => {
+  if (maxItems < 0) {
+    throw new Error("The value of maxItems MUST be a non-negative integer.");
+  }
+
+  return JsonEntityFn((storedJson) => {
+    storedJson.schema.maxItems(maxItems);
+  });
+});

package/src/decorators/collections/maxProperties.spec.ts

@@ -0,0 +1,109 @@
+import {SpecTypes} from "../../domain/SpecTypes.js";
+import {getJsonSchema} from "../../utils/getJsonSchema.js";
+import {getSpec} from "../../utils/getSpec.js";
+import {In} from "../operations/in.js";
+import {OperationPath} from "../operations/operationPath.js";
+import {MaxProperties} from "./maxProperties.js";
+
+describe("@MaxProperties", () => {
+  it("should declare max value (any)", () => {
+    // WHEN
+    class Model {
+      @MaxProperties(10)
+      prop: any;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          maxProperties: 10,
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare max value (Map<any>)", () => {
+    // WHEN
+    class Model {
+      @MaxProperties(10)
+      prop: Map<string, any>;
+    }
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      properties: {
+        prop: {
+          maxProperties: 10,
+          type: "object"
+        }
+      },
+      type: "object"
+    });
+  });
+  it("should declare max value on class", () => {
+    // WHEN
+    @MaxProperties(10)
+    class Model {}
+
+    // THEN
+    expect(getJsonSchema(Model)).toEqual({
+      maxProperties: 10,
+      type: "object"
+    });
+  });
+  it("should declare max value on param", () => {
+    // WHEN
+    class MyController {
+      @OperationPath("POST", "/")
+      method(@In("body") @MaxProperties(10) test: any) {}
+    }
+
+    // THEN
+    expect(getSpec(MyController, {specType: SpecTypes.OPENAPI})).toEqual({
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerMethod",
+            parameters: [],
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    maxProperties: 10,
+                    type: "object"
+                  }
+                }
+              },
+              required: false
+            },
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should throw an error when the given parameters is as negative integer", () => {
+    // WHEN
+    let actualError: any;
+    try {
+      MaxProperties(-1);
+    } catch (er) {
+      actualError = er;
+    }
+
+    // THEN
+    expect(actualError.message).toBe("The value of maxProperties MUST be a non-negative integer.");
+  });
+});