@tsed/schema 8.19.1 → 8.19.3

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

@@ -2,78 +2,112 @@ import { JsonFormatTypes } from "../../domain/JsonFormatTypes.js";
 import { withErrorMsg } from "../../utils/withErrorMsg.js";
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * The following formats are supported for string validation with `format` keyword:
- *
- * - **date**: full-date according to [RFC3339](https://json-schema.org/latest/json-schema-validation.html#RFC3339).
- * - **time**: time with optional time-zone.
- * - **date-time**: date-time from the same source (time-zone is mandatory).
- * - **uri**: full uri with optional protocol.
- * - **email**: email address.
- * - **hostname**: host name according to [RFC1034](https://tools.ietf.org/html/rfc1034#section-3.1).
- * - **ipv4**: IP address v4.
- * - **ipv6**: IP address v6.
- * - **regex**: tests whether a string is a valid regular expression by passing it to RegExp constructor.
+ * Applies a format validation to string properties using JSON Schema's `format` keyword.
  *
- * ::: warning
- * For v6 user, use @@Format@@ from @tsed/schema instead of @tsed/platform-http.
- * :::
+ * The `@Format()` decorator validates string values against common formats like email,
+ * URI, date-time, and IP addresses. This provides semantic validation beyond just checking
+ * the string type.
  *
- * ## Example
- * ### With primitive type
+ * ### Supported Formats
+ *
+ * - **date**: Full-date according to RFC3339 (`2024-01-15`)
+ * - **time**: Time with optional time-zone (`14:30:00`, `14:30:00+02:00`)
+ * - **date-time**: Date-time from RFC3339 (time-zone mandatory: `2024-01-15T14:30:00Z`)
+ * - **uri**: Full URI with optional protocol (`https://example.com/path`)
+ * - **url**: Valid URL (stricter than uri)
+ * - **email**: Email address (`user@example.com`)
+ * - **hostname**: Host name according to RFC1034 (`example.com`)
+ * - **ipv4**: IPv4 address (`192.168.1.1`)
+ * - **ipv6**: IPv6 address (`2001:0db8:85a3::8a2e:0370:7334`)
+ * - **regex**: Valid regular expression pattern
+ *
+ * ### Basic Usage
  *
  * ```typescript
- * class Model {
- *    @Format("email")
- *    property: string;
+ * class ContactModel {
+ *   @Format("email")
+ *   email: string;
+ *
+ *   @Format("uri")
+ *   website: string;
+ *
+ *   @Format("ipv4")
+ *   serverIp: string;
  * }
  * ```
  *
- * ```json
- * {
- *   "type": "object",
- *   "properties": {
- *     "property": {
- *       "type": "string",
- *       "format": "email"
- *     }
- *   }
+ * ### With Arrays
+ *
+ * ```typescript
+ * class ServerConfig {
+ *   @Format("email")
+ *   @CollectionOf(String)
+ *   adminEmails: string[];
+ *   // Each email must be valid
  * }
  * ```
  *
- * ### With array type
+ * ### Date/Time Formats
  *
  * ```typescript
- * class Model {
- *    @Format("email")
- *    @CollectionOf(String)
- *    property: string[];
+ * class EventModel {
+ *   @Format("date")
+ *   eventDate: string;  // "2024-12-25"
+ *
+ *   @Format("time")
+ *   startTime: string;  // "14:30:00"
+ *
+ *   @Format("date-time")
+ *   createdAt: string;  // "2024-01-15T14:30:00Z"
  * }
  * ```
  *
- * Will produce:
+ * ### Convenience Decorators
  *
- * ```json
- * {
- *   "type": "object",
- *   "properties": {
- *     "property": {
- *       "type": "array",
- *       "items": {
- *          "type": "string",
- *          "format": "email"
- *       }
- *     }
- *   }
- * }
+ * Ts.ED provides convenience decorators that use `@Format()` internally:
+ *
+ * - `@Email()` - Equivalent to `@Format("email")`
+ * - `@DateTime()` - Equivalent to `@Format("date-time")`
+ * - `@DateFormat()` - Equivalent to `@Format("date")`
+ * - `@TimeFormat()` - Equivalent to `@Format("time")`
+ * - `@Uri()` - Equivalent to `@Format("uri")`
+ * - `@Url()` - Equivalent to `@Format("url")`
+ *
+ * ### Use Cases
+ *
+ * - **Data Integrity**: Ensure strings conform to expected formats
+ * - **API Validation**: Validate input data at API boundaries
+ * - **Database Constraints**: Match database column format requirements
+ * - **Standards Compliance**: Ensure RFC compliance for dates, emails, URIs
+ *
+ * ### Validation Examples
+ *
+ * ```typescript
+ * @Format("email")
+ * email: string;
+ *
+ * // Valid:
+ * "user@example.com"
+ * "jane.doe+tag@company.co.uk"
+ *
+ * // Invalid:
+ * "not-an-email"
+ * "missing@domain"
+ * "@example.com"
  * ```
  *
- * @param {string} format
+ * ### Important Notes
+ *
+ * - Format validation depends on the validator implementation (AJV, etc.)
+ * - Some formats may require additional validator plugins
+ * - Format is primarily for strings; use on other types may be ignored
+ * - Can be combined with other string validators (MinLength, Pattern, etc.)
+ *
+ * @param format - The format keyword to apply (from JsonFormatTypes enum)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
- * @ajv-errors
+ * @public
  */
 export const Format = withErrorMsg("format", (format) => {
     return JsonEntityFn((store) => {

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

@@ -5,26 +5,92 @@ import { JsonEntityFn } from "./jsonEntityFn.js";
 import { OneOf } from "./oneOf.js";
 import { Property } from "./property.js";
 /**
- * Set field as nullable.
+ * Marks a property as nullable, allowing it to accept `null` in addition to its base type.
  *
- * ## Example
+ * The `@Nullable()` decorator creates a union type that includes `null` alongside the
+ * specified type(s). This is implemented using JSON Schema's `oneOf` keyword to allow
+ * either the specified type or null.
+ *
+ * ### Single Type with Null
  *
  * ```typescript
- * class Model {
- *    @Nullable(Date)
- *    property: Date | null;
+ * class UserModel {
+ *   @Nullable(Date)
+ *   lastLogin: Date | null;
+ *   // Accepts: Date object OR null
+ * }
+ * ```
+ *
+ * ### Multiple Types with Null
  *
- *    @Nullable(String, Number, Boolean)
- *    property: string | number | boolean | null;
+ * ```typescript
+ * class FlexibleModel {
+ *   @Nullable(String, Number, Boolean)
+ *   property: string | number | boolean | null;
+ *   // Accepts: string OR number OR boolean OR null
  * }
  * ```
  *
- * @returns {Function}
+ * ### With Custom Classes
+ *
+ * ```typescript
+ * class Address {
+ *   @Property()
+ *   street: string;
+ * }
+ *
+ * class Person {
+ *   @Nullable(Address)
+ *   address: Address | null;
+ *   // Accepts: Address object OR null
+ * }
+ * ```
+ *
+ * ### TypeScript Integration
+ *
+ * ```typescript
+ * class Product {
+ *   @Nullable(String)
+ *   description: string | null;
+ *
+ *   @Nullable(Number)
+ *   discount: number | null;
+ * }
+ * ```
+ *
+ * ### Important: Arrays
+ *
+ * Do NOT use `@Nullable(Array)` as it produces incorrect schemas. Instead:
+ *
+ * ```typescript
+ * // Wrong
+ * @Nullable(Array)
+ * items: any[] | null;
+ *
+ * // Correct
+ * @Schema(array().items().nullable())
+ * items: any[] | null;
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Optional Database Fields**: Model nullable database columns
+ * - **Partial Updates**: Allow fields to be explicitly set to null in PATCH requests
+ * - **Default Values**: Distinguish between "not provided" and "explicitly null"
+ * - **External APIs**: Match nullable fields from third-party services
+ *
+ * ### vs Optional
+ *
+ * - `@Nullable()`: Field can be present with value `null`
+ * - `@Optional()`: Field can be omitted entirely
+ * - Can combine both: `@Optional() @Nullable(String)` allows omitted, null, or string
+ *
+ * @param type - The primary type that can be null
+ * @param types - Additional types that can be null (creates multi-type union with null)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export function Nullable(type, ...types) {
     types = [type, ...types];

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

@@ -1,18 +1,102 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * See https://tools.ietf.org/html/draft-wright-json-schema-validation-01#section-6.28
+ * Validates that a value must match EXACTLY ONE of the provided schemas (exclusive union).
  *
- * ::: warning
- * OneOf isn't supported by OS2
- * :::
+ * The `oneOf` keyword from JSON Schema requires the value to be valid against exactly
+ * one schema in the list - not zero and not more than one. This is useful for strict
+ * union types where overlapping schemas should be rejected.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * @OneOf(
+ *   { type: "string" },
+ *   { type: "number" }
+ * )
+ * class StringOrNumber {
+ *   // Valid: "hello" OR 42
+ *   // Invalid: true (matches neither), or ambiguous values matching multiple schemas
+ * }
+ * ```
+ *
+ * ### Discriminated Unions
+ *
+ * ```typescript
+ * @OneOf(
+ *   {
+ *     type: "object",
+ *     properties: { type: { const: "email" }, email: { type: "string" } },
+ *     required: ["type", "email"]
+ *   },
+ *   {
+ *     type: "object",
+ *     properties: { type: { const: "phone" }, phone: { type: "string" } },
+ *     required: ["type", "phone"]
+ *   }
+ * )
+ * class Contact {
+ *   // Must be EITHER email contact OR phone contact, not both or neither
+ * }
+ * ```
+ *
+ * ### With Model Classes
+ *
+ * ```typescript
+ * class CreditCard {
+ *   @Const("credit")
+ *   type: "credit";
+ *
+ *   @Property()
+ *   cardNumber: string;
+ * }
+ *
+ * class BankTransfer {
+ *   @Const("bank")
+ *   type: "bank";
+ *
+ *   @Property()
+ *   iban: string;
+ * }
+ *
+ * @OneOf(CreditCard, BankTransfer)
+ * class PaymentMethod {
+ *   // Must be exactly one payment method type
+ * }
+ * ```
+ *
+ * ### Nullable with OneOf
+ *
+ * ```typescript
+ * @OneOf(null, { type: "string" })
+ * class NullableString {
+ *   // Exactly null OR exactly a string
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Strict Union Types**: Enforce exactly one type from a set
+ * - **Discriminated Unions**: Type-safe polymorphic data structures
+ * - **Mutually Exclusive Options**: Ensure only one option is selected
+ * - **Nullable Types**: Combine with null for nullable properties
+ *
+ * ### oneOf vs anyOf vs allOf
+ *
+ * - `@OneOf()`: Must match **exactly one** schema (exclusive)
+ * - `@AnyOf()`: Must match **at least one** schema (inclusive)
+ * - `@AllOf()`: Must match **all** schemas (intersection)
+ *
+ * ### Compatibility Note
+ *
+ * OneOf is not supported by OpenAPI 2.0 (Swagger). For OpenAPI 2.0 compatibility,
+ * consider using discriminator patterns or upgrade to OpenAPI 3.0.
+ *
+ * @param oneOf - Schemas where exactly one must be satisfied
  *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @classDecorator
- * @input
- * @param oneOf
+ * @public
+ * @see https://json-schema.org/understanding-json-schema/reference/combining#oneOf
  */
 export function OneOf(...oneOf) {
     return JsonEntityFn((entity) => {

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

@@ -1,13 +1,102 @@
 import { DecoratorTypes } from "@tsed/core";
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * Add optional annotation on Property or Parameter.
+ * Marks a property or parameter as optional, meaning it can be omitted from the input.
+ *
+ * The `@Optional()` decorator removes the property from the required fields list in the
+ * schema, allowing it to be absent from the object. For parameters, it marks them as
+ * not required in the method signature.
+ *
+ * ### On Properties
+ *
+ * ```typescript
+ * class UserModel {
+ *   @Property()
+ *   name: string;  // Required by default
+ *
+ *   @Optional()
+ *   @Property()
+ *   nickname?: string;  // Optional - can be omitted
+ * }
+ * ```
+ *
+ * ### On Parameters
+ *
+ * ```typescript
+ * @Controller("/users")
+ * class UserController {
+ *   @Get("/:id")
+ *   async get(
+ *     @PathParams("id") id: string,
+ *     @Optional()
+ *     @QueryParams("include") include?: string  // Optional query param
+ *   ) {
+ *     // include can be undefined
+ *   }
+ * }
+ * ```
+ *
+ * ### With Default Values
+ *
+ * ```typescript
+ * class ConfigModel {
+ *   @Optional()
+ *   @Default(10)
+ *   timeout?: number;
+ *   // Optional field with a default value
+ * }
+ * ```
+ *
+ * ### vs Nullable
+ *
+ * - `@Optional()`: Field can be **omitted** entirely from the object
+ * - `@Nullable()`: Field must be **present** but can have value `null`
+ * - Can combine: `@Optional() @Nullable(String)` allows omitted, null, or string
+ *
+ * ### Examples
+ *
+ * ```typescript
+ * // Optional only - field can be omitted
+ * @Optional()
+ * field1?: string;
+ * // Valid: {} or { field1: "value" }
+ * // Invalid: { field1: null }
+ *
+ * // Nullable only - field must be present
+ * @Nullable(String)
+ * field2: string | null;
+ * // Valid: { field2: null } or { field2: "value" }
+ * // Invalid: {}
+ *
+ * // Both - maximum flexibility
+ * @Optional()
+ * @Nullable(String)
+ * field3?: string | null;
+ * // Valid: {}, { field3: null }, { field3: "value" }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Optional Configuration**: Non-required config properties
+ * - **Query Parameters**: Optional filters and options in APIs
+ * - **Partial Updates**: PATCH endpoints where only changed fields are sent
+ * - **Progressive Enhancement**: Features that aren't required for basic functionality
+ *
+ * ### TypeScript Integration
+ *
+ * Use TypeScript's optional property syntax (`?:`) alongside `@Optional()` for
+ * type safety:
+ *
+ * ```typescript
+ * class Model {
+ *   @Optional()
+ *   optionalField?: string;  // TypeScript knows it can be undefined
+ * }
+ * ```
  *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export function Optional() {
     return JsonEntityFn((store) => {

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

@@ -1,14 +1,50 @@
 import { isArrowFn, isClass } from "@tsed/core";
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * Declare a new property on a model.
+ * Declare a property on a model class for schema generation.
+ *
+ * The `@Property()` decorator marks a class property for inclusion in generated
+ * JSON schemas and OpenAPI specifications. It can optionally specify the property's
+ * type, which is useful for arrays, generics, or when TypeScript's reflection
+ * doesn't provide sufficient type information.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * class User {
+ *   // Basic property (type inferred from TypeScript)
+ *   @Property()
+ *   name: string;
+ *
+ *   // Property with explicit type
+ *   @Property(Number)
+ *   age: number;
+ *
+ *   // Array property
+ *   @Property([String])
+ *   tags: string[];
+ *
+ *   // Nested model
+ *   @Property(Address)
+ *   address: Address;
+ *
+ *   // Generic/complex type
+ *   @Property(() => User)
+ *   manager: User;
+ * }
+ * ```
+ *
+ * ### When to Use Explicit Types
+ *
+ * - **Arrays**: Always specify array item types: `@Property([String])`
+ * - **Generics**: Provide concrete types for generic classes
+ * - **Forward References**: Use arrow functions for circular dependencies
+ * - **Complex Types**: When TypeScript metadata is insufficient
+ *
+ * @param type - Optional type definition (class, primitive, array, or arrow function)
  *
- * @param type
  * @decorator
- * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export function Property(type) {
     return JsonEntityFn((store) => {

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

@@ -1,13 +1,114 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * Set the property as readOnly.
+ * Marks a property as read-only, indicating it should not be modified by clients.
+ *
+ * The `@ReadOnly()` decorator sets the `readOnly` flag in the JSON Schema, which signals
+ * to validators and API consumers that this property is for reading only and should not
+ * be included in request payloads. In OpenAPI specs, read-only properties are excluded
+ * from request body schemas but included in response schemas.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * class UserModel {
+ *   @ReadOnly()
+ *   id: string;
+ *   // Server-generated, clients cannot set this
+ *
+ *   @ReadOnly()
+ *   createdAt: Date;
+ *   // Timestamp set by server
+ *
+ *   @Property()
+ *   name: string;
+ *   // Can be read and written
+ * }
+ * ```
+ *
+ * ### Server-Generated Fields
+ *
+ * ```typescript
+ * class PostModel {
+ *   @ReadOnly()
+ *   id: number;
+ *
+ *   @ReadOnly()
+ *   @Default(() => new Date())
+ *   createdAt: Date;
+ *
+ *   @ReadOnly()
+ *   @Default(() => new Date())
+ *   updatedAt: Date;
+ *
+ *   @Property()
+ *   title: string;
+ *
+ *   @Property()
+ *   content: string;
+ * }
+ * ```
+ *
+ * ### Computed Properties
+ *
+ * ```typescript
+ * class OrderModel {
+ *   @Property()
+ *   items: OrderItem[];
+ *
+ *   @ReadOnly()
+ *   get totalPrice(): number {
+ *     return this.items.reduce((sum, item) => sum + item.price, 0);
+ *   }
+ *   // Computed value, clients cannot set it
+ * }
+ * ```
+ *
+ * ### Toggle Read-Only
+ *
+ * ```typescript
+ * class ConfigModel {
+ *   @ReadOnly(true)
+ *   lockedField: string;
+ *   // Read-only
+ *
+ *   @ReadOnly(false)
+ *   editableField: string;
+ *   // Explicitly not read-only (default behavior)
+ * }
+ * ```
+ *
+ * ### OpenAPI Behavior
+ *
+ * In OpenAPI/Swagger documentation:
+ * - Read-only properties appear in **response** schemas
+ * - Read-only properties are **excluded** from **request** schemas
+ * - Helps generate accurate API documentation
+ *
+ * ### vs WriteOnly
+ *
+ * - `@ReadOnly()`: Property can be read but not written (responses only)
+ * - `@WriteOnly()`: Property can be written but not read (requests only)
+ * - Neither: Property can be both read and written
+ *
+ * ### Use Cases
+ *
+ * - **Database IDs**: Auto-generated primary keys
+ * - **Timestamps**: Server-managed created/updated dates
+ * - **Computed Values**: Derived or calculated properties
+ * - **System Metadata**: Internal tracking fields
+ * - **Audit Fields**: Who created/modified records
+ *
+ * ### Security Note
+ *
+ * While `@ReadOnly()` provides documentation and client-side validation hints, it does
+ * not enforce security at the server level. Always validate incoming data server-side
+ * and ignore read-only fields in request payloads.
+ *
+ * @param readOnly - Whether the property is read-only (default: true)
  *
- * @returns {Function}
  * @decorator
  * @validation
- * @property
- * @parameter
- * @schema
+ * @public
  */
 export function ReadOnly(readOnly = true) {
     return JsonEntityFn((store) => {