@tsed/schema 8.19.1 → 8.19.3

package/lib/esm/decorators/common/additionalProperties.js

@@ -1,12 +1,67 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * Accept unknown properties on the deserialized model.
+ * Controls whether additional properties beyond those defined in the schema are allowed.
+ *
+ * By default, JSON Schema validation may allow properties not explicitly defined in the schema.
+ * This decorator lets you control that behavior either by disabling additional properties entirely
+ * or by specifying a schema that additional properties must conform to.
+ *
+ * ### Usage with boolean
+ *
+ * ```typescript
+ * // Disallow any additional properties
+ * @AdditionalProperties(false)
+ * class StrictModel {
+ *   @Property()
+ *   name: string;
+ *   // Any other properties will cause validation errors
+ * }
+ *
+ * // Explicitly allow additional properties (default behavior)
+ * @AdditionalProperties(true)
+ * class FlexibleModel {
+ *   @Property()
+ *   name: string;
+ *   // Additional properties are allowed
+ * }
+ * ```
+ *
+ * ### Usage with schema
+ *
+ * ```typescript
+ * // Additional properties must be strings
+ * @AdditionalProperties({ type: "string" })
+ * class DynamicModel {
+ *   @Property()
+ *   id: number;
+ *   // Other properties must be strings
+ * }
+ *
+ * // Additional properties must match a complex schema
+ * @AdditionalProperties({
+ *   type: "object",
+ *   properties: {
+ *     value: { type: "string" }
+ *   }
+ * })
+ * class MetadataModel {
+ *   @Property()
+ *   name: string;
+ *   // Additional properties must be objects with a 'value' string property
+ * }
+ * ```
+ *
+ * ### Common Use Cases
+ *
+ * - **Strict APIs**: Use `@AdditionalProperties(false)` to ensure clients only send expected fields
+ * - **Dynamic Data**: Use with a schema to validate dynamic property values
+ * - **Migration**: Allow additional properties during API versioning transitions
+ *
+ * @param schema - Boolean to allow/disallow additional properties, or a schema they must match
  *
- * @param schema
  * @decorator
  * @validation
- * @swagger
- * @schema
+ * @public
  */
 export function AdditionalProperties(schema) {
     return JsonEntityFn((entity, parameters) => {

package/lib/esm/decorators/common/allOf.js

@@ -1,14 +1,69 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * See https://tools.ietf.org/html/draft-wright-json-schema-validation-01#section-6.26
+ * Validates that a value must match ALL of the provided schemas (intersection).
+ *
+ * The `allOf` keyword from JSON Schema allows combining multiple schemas where the
+ * value must satisfy every schema in the list. This is useful for:
+ * - Merging multiple schema constraints
+ * - Composing validation rules from different sources
+ * - Creating intersections of object types
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * @AllOf(
+ *   { type: "object", properties: { id: { type: "number" } } },
+ *   { type: "object", properties: { name: { type: "string" } } }
+ * )
+ * class Combined {
+ *   // Must satisfy both schemas
+ *   // Equivalent to: { id: number, name: string }
+ * }
+ * ```
+ *
+ * ### With Model References
+ *
+ * ```typescript
+ * class BaseModel {
+ *   @Property()
+ *   id: number;
+ * }
+ *
+ * class NamedModel {
+ *   @Property()
+ *   name: string;
+ * }
+ *
+ * @AllOf(BaseModel, NamedModel)
+ * class CombinedModel {
+ *   // Inherits validation from both BaseModel and NamedModel
+ * }
+ * ```
+ *
+ * ### Validation Composition
+ *
+ * ```typescript
+ * @AllOf(
+ *   { minProperties: 1 },
+ *   { maxProperties: 10 }
+ * )
+ * class BoundedObject {
+ *   // Must have between 1 and 10 properties
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Mixin Patterns**: Combine validation from multiple models
+ * - **Constraint Merging**: Apply multiple validation rules together
+ * - **Type Intersection**: Create types that must satisfy multiple schemas
+ *
+ * @param allOf - One or more schemas that the value must satisfy
  *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @classDecorator
- * @input
- * @param allOf
+ * @public
+ * @see https://json-schema.org/understanding-json-schema/reference/combining#allOf
  */
 export function AllOf(...allOf) {
     return JsonEntityFn((entity) => {

package/lib/esm/decorators/common/allow.js

@@ -2,31 +2,75 @@ import { DecoratorTypes, isClass, useDecorators } from "@tsed/core";
 import { JsonEntityFn } from "./jsonEntityFn.js";
 import { Property } from "./property.js";
 /**
- * Add allowed values when the property or parameters is required.
+ * Adds specific values to the list of allowed values for required properties or parameters.
  *
- * #### Example on parameter:
+ * When a property or parameter is marked as required, it typically rejects `null`, `undefined`,
+ * and empty strings. The `@Allow()` decorator lets you explicitly permit certain values that
+ * would otherwise fail required validation.
+ *
+ * ### Common Use Case: Allow Empty Strings
+ *
+ * By default, required fields reject empty strings. Use `@Allow("")` to permit them:
  *
  * ```typescript
- * @Post("/")
- * async method(@Allow("") @BodyParams("field") field: string) {}
+ * class UserModel {
+ *   @Required()
+ *   @Allow("")  // Empty string is now valid even though field is required
+ *   nickname: string;
+ * }
  * ```
- * > Required will throw a BadRequest when the given value is `null` or `undefined` but not for an empty string.
  *
- * #### Example on model:
+ * ### On Method Parameters
  *
  * ```typescript
- * class Model {
+ * @Post("/")
+ * async createUser(
  *   @Allow("")
- *   field: string;
+ *   @BodyParams("nickname")
+ *   nickname: string  // Empty string allowed, but null/undefined still rejected
+ * ) {
+ *   // nickname can be "" but not null/undefined
  * }
  * ```
  *
- * @returns {Function}
+ * ### Multiple Allowed Values
+ *
+ * ```typescript
+ * class ConfigModel {
+ *   @Required()
+ *   @Allow(null, "", 0)  // Allow null, empty string, or zero
+ *   threshold: number | null;
+ * }
+ * ```
+ *
+ * ### Combining with Type Specification
+ *
+ * You can specify a model type along with allowed values:
+ *
+ * ```typescript
+ * class FormData {
+ *   @Allow("", SomeModel)  // Allow empty string or a SomeModel instance
+ *   data: SomeModel;
+ * }
+ * ```
+ *
+ * ### Behavior
+ *
+ * - For **parameters**: Automatically marks the parameter as required
+ * - For **properties**: Automatically adds the property to the required list
+ * - Adds specified values to the schema's allowedRequiredValues list
+ *
+ * ### Validation Logic
+ *
+ * Required validation will pass if the value is:
+ * - Not `null`, `undefined`, or `""` (default required behavior)
+ * - OR one of the values specified in `@Allow()`
+ *
+ * @param values - Values to allow even when the field is required (can include a model class)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export function Allow(...values) {
     const model = values.find((item) => isClass(item));

package/lib/esm/decorators/common/any.js

@@ -1,38 +1,78 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * Set the type of the array items.
+ * Allows a property to accept any type or a union of specified types.
  *
- * ## Example
+ * The `@Any()` decorator creates a flexible schema that accepts multiple types. When called
+ * without arguments, it allows all JSON Schema types. When called with specific types, it
+ * restricts to those types only.
+ *
+ * ### Accept All Types
  *
  * ```typescript
- * class Model {
- *    @Any()
- *    property: any;
+ * class FlexibleModel {
+ *   @Any()
+ *   property: any;
+ *   // Accepts: string, number, boolean, object, array, or null
+ * }
+ * ```
  *
- *    @Any(String, Number, Boolean)
- *    property: string | number | boolean;
+ * Generated schema:
+ * ```json
+ * {
+ *   "type": ["integer", "number", "string", "boolean", "array", "object", "null"]
  * }
  * ```
  *
- * Will produce:
+ * ### Restrict to Specific Types
  *
+ * ```typescript
+ * class UnionModel {
+ *   @Any(String, Number, Boolean)
+ *   property: string | number | boolean;
+ *   // Only accepts string, number, or boolean
+ * }
+ * ```
+ *
+ * Generated schema:
  * ```json
  * {
- *   "type": "object",
- *   "properties": {
- *     "property": {
- *       "type": ["integer", "number", "string", "boolean", "array", "object", "null"]
- *     }
- *   }
+ *   "type": ["string", "integer", "number", "boolean"]
  * }
  * ```
  *
- * @returns {Function}
+ * ### With Custom Classes
+ *
+ * ```typescript
+ * class UserModel {
+ *   @Property()
+ *   name: string;
+ * }
+ *
+ * class FlexibleData {
+ *   @Any(String, UserModel)
+ *   data: string | UserModel;
+ *   // Accepts either a string or a UserModel object
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Dynamic Data**: When property type varies based on runtime conditions
+ * - **Migrations**: During API transitions when type requirements change
+ * - **Polymorphic Data**: When different types are valid in the same field
+ * - **Third-party Integration**: When dealing with untyped external data
+ *
+ * ### Considerations
+ *
+ * - More specific decorators like `@String()`, `@Number()` provide better validation
+ * - Consider using `@OneOf()` or `@AnyOf()` for complex type unions with constraints
+ * - Overuse of `@Any()` can reduce type safety benefits
+ *
+ * @param types - Optional list of types to restrict to (if omitted, allows all types)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export function Any(...types) {
     return JsonEntityFn((store) => {

package/lib/esm/decorators/common/anyOf.js

@@ -1,18 +1,74 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * See https://tools.ietf.org/html/draft-wright-json-schema-validation-01#section-6.27
+ * Validates that a value must match AT LEAST ONE of the provided schemas (union).
  *
- * ::: warning
- * AnyOf isn't supported by OS2
- * :::
+ * The `anyOf` keyword from JSON Schema allows combining multiple schemas where the
+ * value must satisfy at least one schema in the list. This is useful for creating
+ * union types with different validation rules for each variant.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * @AnyOf(
+ *   { type: "string", minLength: 5 },
+ *   { type: "number", minimum: 100 }
+ * )
+ * class StringOrLargeNumber {
+ *   // Valid: "hello" (string >= 5 chars) OR 150 (number >= 100)
+ *   // Invalid: "hi" (too short) OR 50 (too small)
+ * }
+ * ```
+ *
+ * ### With Model References
+ *
+ * ```typescript
+ * class EmailContact {
+ *   @Property()
+ *   @Email()
+ *   email: string;
+ * }
+ *
+ * class PhoneContact {
+ *   @Property()
+ *   @Pattern(/^\d{10}$/)
+ *   phone: string;
+ * }
+ *
+ * @AnyOf(EmailContact, PhoneContact)
+ * class Contact {
+ *   // Must be either a valid EmailContact OR a valid PhoneContact
+ * }
+ * ```
+ *
+ * ### Multiple Constraints
+ *
+ * ```typescript
+ * @AnyOf(
+ *   { type: "object", required: ["id"] },
+ *   { type: "object", required: ["name"] }
+ * )
+ * class FlexibleIdentifier {
+ *   // Must have either 'id' property OR 'name' property (or both)
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Union Types**: Model TypeScript union types with validation
+ * - **Alternative Formats**: Accept data in multiple valid formats
+ * - **Flexible APIs**: Support different request shapes in the same endpoint
+ *
+ * ### Compatibility Note
+ *
+ * AnyOf is not supported by OpenAPI 2.0 (Swagger). For OpenAPI 2.0 compatibility,
+ * consider using simpler alternatives or upgrade to OpenAPI 3.0.
+ *
+ * @param anyOf - One or more schemas where at least one must be satisfied
  *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @classDecorator
- * @input
- * @param anyOf
+ * @public
+ * @see https://json-schema.org/understanding-json-schema/reference/combining#anyOf
  */
 export function AnyOf(...anyOf) {
     return JsonEntityFn((entity) => {

package/lib/esm/decorators/common/const.js

@@ -1,62 +1,104 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * The const keyword is used to restrict a value to a fixed value.
+ * Restricts a property to a single fixed value using JSON Schema's `const` keyword.
  *
- * ::: warning
- * For v6 user, use @@Const@@ from @tsed/schema instead of @tsed/platform-http.
- * :::
+ * The `@Const()` decorator ensures that a property must have exactly the specified value.
+ * This is useful for literal types, discriminator fields, API version indicators, and
+ * other cases where only one specific value is valid.
  *
- * ## Example
- * ### With a string
+ * ### String Constants
  *
  * ```typescript
- * class Model {
- *    @Const("value1")
- *    property: "value1";
+ * class ApiResponse {
+ *   @Const("success")
+ *   status: "success";
+ *   // Only "success" is valid, any other value fails validation
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
  *   "properties": {
- *     "property": {
+ *     "status": {
  *       "type": "string",
- *       "const": "value1"
+ *       "const": "success"
  *     }
  *   }
  * }
  * ```
- *  * ### With a boolean
+ *
+ * ### Number Constants
  *
  * ```typescript
- * class Model {
- *    @Const(true)
- *    property: boolean;
+ * class ConfigModel {
+ *   @Const(1)
+ *   version: 1;
+ *   // Only version 1 is accepted
  * }
  * ```
  *
- * Will produce:
+ * ### Boolean Constants
  *
- * ```json
- * {
- *   "type": "object",
- *   "properties": {
- *     "property": {
- *       "type": "boolean",
- *       "const": true
- *     }
- *   }
+ * ```typescript
+ * class FeatureFlag {
+ *   @Const(true)
+ *   enabled: true;
+ *   // Must always be true
  * }
  * ```
  *
- * @param {string | number | boolean } constValue
+ * ### Discriminator Pattern
+ *
+ * ```typescript
+ * class DogAnimal {
+ *   @Const("dog")
+ *   type: "dog";
+ *
+ *   @Property()
+ *   breed: string;
+ * }
+ *
+ * class CatAnimal {
+ *   @Const("cat")
+ *   type: "cat";
+ *
+ *   @Property()
+ *   indoor: boolean;
+ * }
+ * ```
+ *
+ * ### API Versioning
+ *
+ * ```typescript
+ * class V2Request {
+ *   @Const("v2")
+ *   apiVersion: "v2";
+ *
+ *   @Property()
+ *   data: any;
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Type Discriminators**: Distinguish between union type variants
+ * - **Literal Types**: Enforce TypeScript literal types at runtime
+ * - **API Versioning**: Validate API version in requests
+ * - **Status Fields**: Ensure specific status values in responses
+ * - **Configuration**: Lock configuration values to specific constants
+ *
+ * ### vs Enum
+ *
+ * - `@Const()`: Single fixed value only
+ * - `@Enum()`: Multiple allowed values from a set
+ *
+ * @param constValue - The exact value that this property must have
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
+ * @public
  */
 export function Const(constValue) {
     return JsonEntityFn((store) => {