@tsed/schema 8.19.2 → 8.19.3

package/lib/esm/decorators/collections/maxItems.js

@@ -1,51 +1,121 @@
 import { withErrorMsg } from "../../utils/withErrorMsg.js";
 import { JsonEntityFn } from "../common/jsonEntityFn.js";
 /**
- * The value `maxItems` MUST be a non-negative integer.
+ * Sets the maximum number of items allowed in an array.
  *
- * An array instance is valid against `maxItems` if its size is less than, or equal to, the value of this keyword.
+ * The `@MaxItems()` decorator validates that an array has at most the specified number
+ * of elements. This is useful for enforcing size limits on collections to prevent
+ * excessive data, manage performance, or enforce business rules.
  *
- * :: 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
+ * ### Basic Usage
  *
  * ```typescript
- * class Model {
- *    @CollectionOf(String)
- *    @MaxItems(10)
- *    property: string[];
+ * class UserModel {
+ *   @CollectionOf(String)
+ *   @MaxItems(5)
+ *   tags: string[];
+ *   // Maximum 5 tags allowed
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
  *   "properties": {
- *     "property": {
- *       "type": "number",
- *       "maxItems": 10
+ *     "tags": {
+ *       "type": "array",
+ *       "maxItems": 5,
+ *       "items": {
+ *         "type": "string"
+ *       }
  *     }
  *   }
  * }
  * ```
  *
- * @param {number} maxItems
+ * ### With MinItems - Range Validation
+ *
+ * ```typescript
+ * class TeamModel {
+ *   @CollectionOf(String)
+ *   @MinItems(1)
+ *   @MaxItems(10)
+ *   members: string[];
+ *   // Must have between 1 and 10 members
+ * }
+ * ```
+ *
+ * ### API Rate Limiting
+ *
+ * ```typescript
+ * class BulkRequest {
+ *   @CollectionOf(Number)
+ *   @MaxItems(100)
+ *   ids: number[];
+ *   // Limit bulk operations to 100 items
+ * }
+ * ```
+ *
+ * ### File Uploads
+ *
+ * ```typescript
+ * class FileUpload {
+ *   @CollectionOf(Object)
+ *   @MaxItems(5)
+ *   attachments: File[];
+ *   // Maximum 5 file attachments
+ * }
+ * ```
+ *
+ * ### Validation Examples
+ *
+ * ```typescript
+ * @MaxItems(3)
+ * items: string[];
+ *
+ * // Valid:
+ * []                    // 0 items (≤ 3)
+ * ["a"]                 // 1 item (≤ 3)
+ * ["a", "b", "c"]       // 3 items (≤ 3)
+ *
+ * // Invalid:
+ * ["a", "b", "c", "d"]  // 4 items (> 3)
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Performance**: Limit collection sizes to prevent memory issues
+ * - **Business Rules**: Enforce maximum quantities (cart items, selections)
+ * - **API Protection**: Prevent abuse with excessive bulk requests
+ * - **UI Constraints**: Match front-end limitations (max selections)
+ * - **Data Quality**: Encourage focused, manageable data sets
+ *
+ * ### Combining with Other Validators
+ *
+ * ```typescript
+ * class SearchQuery {
+ *   @CollectionOf(String)
+ *   @MinItems(1)
+ *   @MaxItems(10)
+ *   @UniqueItems()
+ *   keywords: string[];
+ *   // 1-10 unique search keywords
+ * }
+ * ```
+ *
+ * ### Important Notes
+ *
+ * - The value must be a **non-negative integer** (0 or greater)
+ * - Throws an error if a negative value is provided
+ * - Empty arrays (length 0) always pass maxItems validation
+ * - Can be combined with custom error messages using ajv-errors
+ *
+ * @param maxItems - Maximum number of items allowed (must be non-negative)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
- * @collections
- * @ajv-errors
+ * @public
  */
 export const MaxItems = withErrorMsg("maxItems", (maxItems) => {
     if (maxItems < 0) {

package/lib/esm/decorators/collections/maxProperties.js

@@ -1,50 +1,45 @@
 import { withErrorMsg } from "../../utils/withErrorMsg.js";
 import { JsonEntityFn } from "../common/jsonEntityFn.js";
 /**
- * An object instance is valid against `maxProperties` if its number of properties is less than, or equal to, the value of this keyword.
+ * Sets the maximum number of properties allowed on an object.
  *
- * ::: warning
- * The value of this keyword MUST be a non-negative integer.
- * :::
+ * The `@MaxProperties()` decorator validates that an object has at most the specified
+ * number of properties. This is useful for limiting dynamic object sizes, preventing
+ * excessive data structures, or enforcing schema constraints on flexible objects.
  *
- * ::: warning
- * This decorator will be removed in v7.
- * For v6 user, use @@MaxProperties@@ from @tsed/schema instead of @tsed/platform-http.
- * :::
+ * ### On Property
  *
- * ## Example
- * ### On prop
  * ```typescript
- * class Model {
- *    @MaxProperties(10)
- *    property: any;
+ * class ConfigModel {
+ *   @MaxProperties(5)
+ *   metadata: Record<string, any>;
+ *   // Object can have at most 5 properties
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
  *   "properties": {
- *     "property": {
- *       "type": "any",
- *       "maxProperties": 10
+ *     "metadata": {
+ *       "type": "object",
+ *       "maxProperties": 5
  *     }
  *   }
  * }
  * ```
  *
- * ### On class
+ * ### On Class
  *
  * ```typescript
  * @MaxProperties(10)
- * class Model {
+ * class DynamicModel {
+ *   // Class instances can have at most 10 properties total
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
@@ -55,20 +50,91 @@ import { JsonEntityFn } from "../common/jsonEntityFn.js";
  * ### On Parameter
  *
  * ```typescript
+ * @Controller("/api")
+ * class ApiController {
+ *   @Post("/config")
+ *   updateConfig(
+ *     @BodyParams() @MaxProperties(10) config: any
+ *   ) {
+ *     // Config object limited to 10 properties
+ *   }
+ * }
+ * ```
+ *
+ * ### With MinProperties - Range Validation
+ *
+ * ```typescript
+ * class FilterModel {
+ *   @MinProperties(1)
+ *   @MaxProperties(5)
+ *   filters: Record<string, string>;
+ *   // Must have 1-5 filter properties
+ * }
+ * ```
+ *
+ * ### Dynamic Objects
+ *
+ * ```typescript
+ * class UserPreferences {
+ *   @MaxProperties(20)
+ *   @AdditionalProperties({ type: "string" })
+ *   settings: Record<string, string>;
+ *   // Up to 20 custom settings, all string values
+ * }
+ * ```
+ *
+ * ### Validation Examples
+ *
+ * ```typescript
+ * @MaxProperties(2)
+ * data: object;
+ *
+ * // Valid:
+ * {}                         // 0 properties (≤ 2)
+ * { a: 1 }                   // 1 property (≤ 2)
+ * { a: 1, b: 2 }             // 2 properties (≤ 2)
+ *
+ * // Invalid:
+ * { a: 1, b: 2, c: 3 }       // 3 properties (> 2)
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **API Rate Limiting**: Restrict filter/query parameter counts
+ * - **Performance**: Prevent overly complex objects
+ * - **Schema Constraints**: Limit dynamic data structures
+ * - **Configuration**: Cap number of custom settings
+ * - **Security**: Prevent payload bloat attacks
  *
- * class Model {
- *   method(@Any() @MaxProperties(10) obj: any){}
+ * ### Flexible Schemas
+ *
+ * ```typescript
+ * class ExtensibleModel {
+ *   @Property()
+ *   id: string;
+ *
+ *   @Property()
+ *   name: string;
+ *
+ *   @MaxProperties(5)
+ *   @AdditionalProperties(true)
+ *   // 2 defined properties + up to 3 additional properties
  * }
  * ```
  *
- * @param {number} maxProperties The maximum properties allowed on the given object
+ * ### Important Notes
+ *
+ * - The value must be a **non-negative integer** (0 or greater)
+ * - Throws an error if a negative value is provided
+ * - Empty objects (`{}`) always pass maxProperties validation
+ * - Counts all properties, including inherited and additional ones
+ * - Can be combined with custom error messages using ajv-errors
+ *
+ * @param maxProperties - Maximum number of properties allowed (must be non-negative)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
- * @collections
- * @ajv-errors
+ * @public
  */
 export const MaxProperties = withErrorMsg("maxProperties", (maxProperties) => {
     if (maxProperties < 0) {

package/lib/esm/decorators/collections/minItems.js

@@ -1,39 +1,31 @@
 import { withErrorMsg } from "../../utils/withErrorMsg.js";
 import { JsonEntityFn } from "../common/jsonEntityFn.js";
 /**
- * An array instance is valid against `minItems` if its size is greater than, or equal to, the value of this keyword.
+ * Sets the minimum number of items required in an array.
  *
- * ::: warning
- * The value `minItems` MUST be a non-negative integer.
- * :::
+ * The `@MinItems()` decorator validates that an array has at least the specified number
+ * of elements. This is useful for ensuring required data is provided, enforcing business
+ * rules, or guaranteeing minimum quantities.
  *
- * ::: tip
- * Omitting this keyword has the same behavior as a value of 0.
- * :::
- *
- * ::: warning
- * For v6 user, use @@MinItems@@ from @tsed/schema instead of @tsed/platform-http.
- * :::
- *
- * ## Example
+ * ### Basic Usage
  *
  * ```typescript
- * class Model {
- *    @CollectionOf(String)
- *    @MinItems(10)
- *    property: string[];
+ * class OrderModel {
+ *   @CollectionOf(String)
+ *   @MinItems(1)
+ *   items: string[];
+ *   // Order must have at least 1 item
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
  *   "properties": {
- *     "property": {
+ *     "items": {
  *       "type": "array",
- *       "minItems": 10,
+ *       "minItems": 1,
  *       "items": {
  *         "type": "string"
  *       }
@@ -42,14 +34,117 @@ import { JsonEntityFn } from "../common/jsonEntityFn.js";
  * }
  * ```
  *
- * @param {number} minItems
+ * ### With MaxItems - Range Validation
+ *
+ * ```typescript
+ * class VotingModel {
+ *   @CollectionOf(String)
+ *   @MinItems(3)
+ *   @MaxItems(10)
+ *   candidates: string[];
+ *   // Must have between 3 and 10 candidates
+ * }
+ * ```
+ *
+ * ### Required Selections
+ *
+ * ```typescript
+ * class SurveyResponse {
+ *   @CollectionOf(String)
+ *   @MinItems(1)
+ *   selectedOptions: string[];
+ *   // User must select at least one option
+ * }
+ * ```
+ *
+ * ### Business Rules
+ *
+ * ```typescript
+ * class TeamCreation {
+ *   @CollectionOf(String)
+ *   @MinItems(2)
+ *   memberIds: string[];
+ *   // Team requires minimum 2 members
+ * }
+ * ```
+ *
+ * ### Validation Examples
+ *
+ * ```typescript
+ * @MinItems(2)
+ * items: string[];
+ *
+ * // Valid:
+ * ["a", "b"]              // 2 items (≥ 2)
+ * ["a", "b", "c"]         // 3 items (≥ 2)
+ *
+ * // Invalid:
+ * []                      // 0 items (< 2)
+ * ["a"]                   // 1 item (< 2)
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Required Data**: Ensure minimum data is provided
+ * - **Business Logic**: Enforce minimum quantities (team size, votes)
+ * - **Data Quality**: Prevent submission with insufficient information
+ * - **User Input**: Require multiple selections or answers
+ * - **Validation**: Ensure arrays are not empty when data is expected
+ *
+ * ### Non-Empty Arrays
+ *
+ * ```typescript
+ * class CommentModel {
+ *   @CollectionOf(String)
+ *   @MinItems(1)
+ *   tags: string[];
+ *   // Prevent empty tag arrays
+ * }
+ * ```
+ *
+ * ### Combining with Uniqueness
+ *
+ * ```typescript
+ * class CategoryModel {
+ *   @CollectionOf(String)
+ *   @MinItems(2)
+ *   @UniqueItems()
+ *   subcategories: string[];
+ *   // Must have at least 2 unique subcategories
+ * }
+ * ```
+ *
+ * ### Important Notes
+ *
+ * - The value must be a **non-negative integer** (0 or greater)
+ * - Throws an error if a negative value is provided
+ * - Omitting `@MinItems()` is equivalent to `@MinItems(0)` (no minimum)
+ * - Can be combined with custom error messages using ajv-errors
+ * - Arrays with exactly minItems elements are valid (inclusive)
+ *
+ * ### Default Behavior
+ *
+ * Without `@MinItems()`, arrays can be empty:
+ * ```typescript
+ * @CollectionOf(String)
+ * tags: string[];
+ * // Valid: [], ["tag1"], ["tag1", "tag2"], etc.
+ * ```
+ *
+ * With `@MinItems(1)`, empty arrays are rejected:
+ * ```typescript
+ * @CollectionOf(String)
+ * @MinItems(1)
+ * tags: string[];
+ * // Invalid: []
+ * // Valid: ["tag1"], ["tag1", "tag2"], etc.
+ * ```
+ *
+ * @param minItems - Minimum number of items required (must be non-negative)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
- * @collections
- * @ajv-errors
+ * @public
  */
 export const MinItems = withErrorMsg("minItems", (minItems) => {
     if (minItems < 0) {

package/lib/esm/decorators/collections/minProperties.js

@@ -1,73 +1,174 @@
 import { withErrorMsg } from "../../utils/withErrorMsg.js";
 import { JsonEntityFn } from "../common/jsonEntityFn.js";
 /**
- * An object instance is valid against `minProperties` if its number of properties is less than, or equal to, the value of this keyword.
+ * Sets the minimum number of properties required on an object.
  *
- * ::: warning
- * The value of this keyword MUST be a non-negative integer.
- * :::
+ * The `@MinProperties()` decorator validates that an object has at least the specified
+ * number of properties. This is useful for ensuring objects aren't empty, enforcing
+ * minimum data requirements, or validating that dynamic objects have sufficient content.
  *
- * ::: warning
- * For v6 user, use @@MinProperties@@ from @tsed/schema instead of @tsed/platform-http.
- * :::
+ * ### On Property
  *
- * ## Example
- * ### On prop
  * ```typescript
- * class Model {
- *    @MinProperties(10)
- *    property: any;
+ * class DataModel {
+ *   @MinProperties(1)
+ *   attributes: Record<string, any>;
+ *   // Object must have at least 1 property
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
  *   "properties": {
- *     "property": {
- *       "type": "any",
- *       "minProperties": 10
+ *     "attributes": {
+ *       "type": "object",
+ *       "minProperties": 1
  *     }
  *   }
  * }
  * ```
  *
- * ### On class
+ * ### On Class
  *
  * ```typescript
- * @MinProperties(10)
- * class Model {
+ * @MinProperties(2)
+ * class RequiredDataModel {
+ *   // Class instances must have at least 2 properties
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
- *   "minProperties": 10
+ *   "minProperties": 2
  * }
  * ```
  *
  * ### On Parameter
  *
  * ```typescript
+ * @Controller("/api")
+ * class ApiController {
+ *   @Post("/filters")
+ *   search(
+ *     @BodyParams() @MinProperties(1) filters: any
+ *   ) {
+ *     // Filters object must have at least 1 property
+ *   }
+ * }
+ * ```
+ *
+ * ### With MaxProperties - Range Validation
+ *
+ * ```typescript
+ * class MetadataModel {
+ *   @MinProperties(2)
+ *   @MaxProperties(10)
+ *   metadata: Record<string, string>;
+ *   // Must have between 2 and 10 properties
+ * }
+ * ```
+ *
+ * ### Non-Empty Objects
+ *
+ * ```typescript
+ * class SearchCriteria {
+ *   @MinProperties(1)
+ *   criteria: Record<string, any>;
+ *   // Prevent empty search criteria objects
+ * }
+ * ```
+ *
+ * ### Dynamic Configuration
+ *
+ * ```typescript
+ * class PluginConfig {
+ *   @MinProperties(1)
+ *   @AdditionalProperties({ type: "string" })
+ *   options: Record<string, string>;
+ *   // At least 1 configuration option required
+ * }
+ * ```
+ *
+ * ### Validation Examples
+ *
+ * ```typescript
+ * @MinProperties(2)
+ * data: object;
  *
- * class Model {
- *   method(@Any() @MinProperties(10) obj: any){}
+ * // Valid:
+ * { a: 1, b: 2 }             // 2 properties (≥ 2)
+ * { a: 1, b: 2, c: 3 }       // 3 properties (≥ 2)
+ *
+ * // Invalid:
+ * {}                         // 0 properties (< 2)
+ * { a: 1 }                   // 1 property (< 2)
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Required Data**: Ensure objects have minimum content
+ * - **Non-Empty Objects**: Prevent empty dynamic objects
+ * - **Business Rules**: Enforce minimum configuration requirements
+ * - **API Validation**: Require sufficient filter/search criteria
+ * - **Data Quality**: Ensure objects contain meaningful data
+ *
+ * ### Filter Validation
+ *
+ * ```typescript
+ * class QueryModel {
+ *   @MinProperties(1)
+ *   filters: Record<string, string>;
+ *   // Must specify at least one filter
  * }
  * ```
  *
- * @param {number} minProperties The minimum properties allowed on the object.
+ * ### Combining with AdditionalProperties
+ *
+ * ```typescript
+ * class FlexibleModel {
+ *   @Property()
+ *   id: string;
+ *
+ *   @MinProperties(3)
+ *   @AdditionalProperties({ type: "string" })
+ *   // 1 defined property + at least 2 additional properties = 3 minimum
+ * }
+ * ```
+ *
+ * ### Important Notes
+ *
+ * - The value must be a **non-negative integer** (0 or greater)
+ * - Throws an error if a negative value is provided
+ * - Omitting `@MinProperties()` is equivalent to `@MinProperties(0)` (no minimum)
+ * - Counts all properties, including defined and additional ones
+ * - Objects with exactly minProperties count are valid (inclusive)
+ * - Can be combined with custom error messages using ajv-errors
+ *
+ * ### Default Behavior
+ *
+ * Without `@MinProperties()`, empty objects are valid:
+ * ```typescript
+ * data: Record<string, any>;
+ * // Valid: {}, { a: 1 }, { a: 1, b: 2 }, etc.
+ * ```
+ *
+ * With `@MinProperties(1)`, empty objects are rejected:
+ * ```typescript
+ * @MinProperties(1)
+ * data: Record<string, any>;
+ * // Invalid: {}
+ * // Valid: { a: 1 }, { a: 1, b: 2 }, etc.
+ * ```
+ *
+ * @param minProperties - Minimum number of properties required (must be non-negative)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
- * @collections
- * @ajv-errors
+ * @public
  */
 export const MinProperties = withErrorMsg("minProperties", (minProperties) => {
     if (minProperties < 0) {