@tsed/schema 8.19.2 → 8.19.3

package/lib/types/decorators/common/customKey.d.ts

@@ -1,26 +1,146 @@
 /**
- * Set a custom key on JsonSchema that is not a part of the official spec.
+ * Adds a custom key-value pair to the JSON Schema that is not part of the official spec.
  *
- * This custom key can only be displayed if the @@getJsonSchema@@ is called with `{customKeys: true}`.
+ * The `@CustomKey()` decorator allows adding vendor-specific extensions or custom metadata
+ * to schemas. These custom keys are only included in the generated schema when explicitly
+ * requested with the `customKeys: true` option in `getJsonSchema()`.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * class UserModel {
+ *   @CustomKey("x-internal-id", "USER_001")
+ *   @Property()
+ *   username: string;
+ * }
+ * ```
+ *
+ * ### Vendor Extensions
+ *
+ * Following OpenAPI conventions, use `x-` prefix for custom extensions:
+ *
+ * ```typescript
+ * class ApiModel {
+ *   @CustomKey("x-visibility", "internal")
+ *   @CustomKey("x-deprecated-by", "newField")
+ *   @Property()
+ *   oldField: string;
+ * }
+ * ```
+ *
+ * ### Documentation Metadata
+ *
+ * ```typescript
+ * class ProductModel {
+ *   @CustomKey("x-example-source", "marketing-team")
+ *   @CustomKey("x-last-reviewed", "2024-01-15")
+ *   @Property()
+ *   description: string;
+ * }
+ * ```
+ *
+ * ### Integration Hints
+ *
+ * ```typescript
+ * class DataModel {
+ *   @CustomKey("x-database-column", "user_full_name")
+ *   @CustomKey("x-searchable", true)
+ *   @Property()
+ *   fullName: string;
+ * }
+ * ```
+ *
+ * ### Retrieving Custom Keys
+ *
+ * Custom keys must be explicitly requested:
+ *
+ * ```typescript
+ * import { getJsonSchema } from "@tsed/schema";
+ *
+ * const schema = getJsonSchema(UserModel, { customKeys: true });
+ * // Schema will include x-internal-id and other custom keys
+ *
+ * const standardSchema = getJsonSchema(UserModel);
+ * // Custom keys are omitted by default
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **OpenAPI Extensions**: Add vendor-specific OpenAPI extensions
+ * - **Tool Integration**: Metadata for code generators or documentation tools
+ * - **Internal Tracking**: Development or operational metadata
+ * - **Feature Flags**: Schema-level feature flag information
+ * - **Database Mapping**: ORM or database column hints
+ *
+ * @param key - The custom key name (use `x-` prefix for vendor extensions)
+ * @param value - The value to associate with the key
  *
- * @returns {Function}
  * @decorator
  * @validation
- * @property
- * @parameter
- * @schema
+ * @public
  */
 export declare function CustomKey(key: string, value: any): (...args: any[]) => any;
 /**
- * Set a group of custom keys on JsonSchema that is not a part of the official spec.
+ * Adds multiple custom key-value pairs to the JSON Schema in one decorator.
+ *
+ * The `@CustomKeys()` decorator is a convenience function for adding multiple custom
+ * keys at once. Like `@CustomKey()`, these keys are only included when explicitly
+ * requested with `customKeys: true`.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * class ProductModel {
+ *   @CustomKeys({
+ *     "x-internal-code": "PROD-123",
+ *     "x-category": "electronics",
+ *     "x-priority": "high"
+ *   })
+ *   @Property()
+ *   name: string;
+ * }
+ * ```
+ *
+ * ### Multiple Vendor Extensions
+ *
+ * ```typescript
+ * class ApiEndpoint {
+ *   @CustomKeys({
+ *     "x-rate-limit": 100,
+ *     "x-requires-auth": true,
+ *     "x-cache-ttl": 3600,
+ *     "x-deprecated": false
+ *   })
+ *   @Property()
+ *   endpoint: string;
+ * }
+ * ```
+ *
+ * ### Equivalent to Multiple @CustomKey
+ *
+ * These are equivalent:
+ *
+ * ```typescript
+ * // Using @CustomKeys
+ * @CustomKeys({ "x-foo": "bar", "x-baz": "qux" })
+ * field: string;
+ *
+ * // Using multiple @CustomKey
+ * @CustomKey("x-foo", "bar")
+ * @CustomKey("x-baz", "qux")
+ * field: string;
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Bulk Metadata**: Add multiple related custom properties efficiently
+ * - **Configuration**: Group related custom configuration values
+ * - **Tool Directives**: Multiple hints for code generation or documentation
  *
- * This custom key can only be displayed if the @@getJsonSchema@@ is called with `{customKeys: true}`.
+ * @param obj - Object containing custom key-value pairs
  *
- * @returns {Function}
  * @decorator
  * @validation
- * @property
- * @parameter
- * @schema
+ * @public
  */
 export declare function CustomKeys(obj: Record<string, any>): (...args: any[]) => any;

package/lib/types/decorators/common/default.d.ts

@@ -1,42 +1,108 @@
 import type { JSONSchema7Type } from "json-schema";
 /**
- * There are no restrictions placed on the value of this keyword.
+ * Specifies a default value for a property in the JSON Schema.
  *
- * ::: warning
- * For v6 user, use @@Default@@ from @tsed/schema instead of @tsed/platform-http.
- * :::
+ * The `@Default()` decorator sets the default value that should be used when a property
+ * is not provided in the input. This is primarily used for documentation in OpenAPI specs
+ * and can be used by validation libraries that support default value insertion.
  *
- * This keyword can be used to supply a default JSON value associated with a particular schema.
- * It is RECOMMENDED that a default value be valid against the associated schema.
- *
- * ## Example
+ * ### Basic Usage
  *
  * ```typescript
- * class Model {
- *    @Default("10")
- *    property: string = "10";
+ * class UserModel {
+ *   @Default("guest")
+ *   role: string = "guest";
+ *
+ *   @Default(0)
+ *   loginCount: number = 0;
+ *
+ *   @Default(true)
+ *   active: boolean = true;
  * }
  * ```
  *
- * Will produce:
- *
+ * Generated schema:
  * ```json
  * {
  *   "type": "object",
  *   "properties": {
- *     "property": {
+ *     "role": {
  *       "type": "string",
- *       "default": "10"
+ *       "default": "guest"
+ *     },
+ *     "loginCount": {
+ *       "type": "integer",
+ *       "default": 0
+ *     },
+ *     "active": {
+ *       "type": "boolean",
+ *       "default": true
  *     }
  *   }
  * }
  * ```
  *
- * @param {string | number | boolean | {}} defaultValue
+ * ### With Objects
+ *
+ * ```typescript
+ * class ConfigModel {
+ *   @Default({ theme: "light", lang: "en" })
+ *   preferences: object = { theme: "light", lang: "en" };
+ * }
+ * ```
+ *
+ * ### With Arrays
+ *
+ * ```typescript
+ * class ListModel {
+ *   @Default([])
+ *   items: string[] = [];
+ * }
+ * ```
+ *
+ * ### Dynamic Defaults with Functions
+ *
+ * ```typescript
+ * class TimestampModel {
+ *   @Default(() => new Date().toISOString())
+ *   createdAt: string;
+ *   // Default value computed at schema generation time
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Optional Configuration**: Provide sensible defaults for config properties
+ * - **API Documentation**: Show default values in OpenAPI/Swagger docs
+ * - **Form Generation**: Pre-populate form fields with default values
+ * - **Database Models**: Document default column values
+ *
+ * ### Important Notes
+ *
+ * - The decorator adds default info to the schema but doesn't set TypeScript property initializers
+ * - Recommended to match TypeScript initializer with decorator value for consistency
+ * - Default value should be valid according to the property's schema
+ * - Not all validation libraries automatically apply defaults
+ *
+ * ### With Validation
+ *
+ * ```typescript
+ * class PaginationParams {
+ *   @Default(10)
+ *   @Minimum(1)
+ *   @Maximum(100)
+ *   limit: number = 10;
+ *
+ *   @Default(0)
+ *   @Minimum(0)
+ *   offset: number = 0;
+ * }
+ * ```
+ *
+ * @param defaultValue - The default value (or function returning the value)
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export declare function Default(defaultValue: JSONSchema7Type | undefined | (() => JSONSchema7Type)): (...args: any[]) => any;

package/lib/types/decorators/common/discriminatorKey.d.ts

@@ -1 +1,124 @@
+/**
+ * Marks a property as the discriminator key for polymorphic type resolution.
+ *
+ * The `@DiscriminatorKey()` decorator identifies which property in a base class should
+ * be used to determine the concrete type in inheritance hierarchies. This is essential
+ * for proper serialization/deserialization of polymorphic objects and for generating
+ * accurate OpenAPI schemas with discriminators.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * abstract class Animal {
+ *   @DiscriminatorKey()
+ *   type: string;
+ *
+ *   @Property()
+ *   name: string;
+ * }
+ *
+ * @DiscriminatorValue("dog")
+ * class Dog extends Animal {
+ *   @Property()
+ *   breed: string;
+ * }
+ *
+ * @DiscriminatorValue("cat")
+ * class Cat extends Animal {
+ *   @Property()
+ *   indoor: boolean;
+ * }
+ * ```
+ *
+ * ### How It Works
+ *
+ * When deserializing, the framework:
+ * 1. Reads the discriminator key property value
+ * 2. Maps it to the correct concrete class using `@DiscriminatorValue()`
+ * 3. Instantiates and validates the appropriate subclass
+ *
+ * ### With API Endpoints
+ *
+ * ```typescript
+ * @Controller("/animals")
+ * class AnimalController {
+ *   @Post("/")
+ *   async create(@BodyParams() animal: Animal) {
+ *     // animal is automatically deserialized to Dog or Cat
+ *     // based on the 'type' field in the request body
+ *   }
+ * }
+ * ```
+ *
+ * ### OpenAPI Generation
+ *
+ * Generates discriminator object in OpenAPI spec:
+ *
+ * ```json
+ * {
+ *   "discriminator": {
+ *     "propertyName": "type",
+ *     "mapping": {
+ *       "dog": "#/components/schemas/Dog",
+ *       "cat": "#/components/schemas/Cat"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Payment Method Example
+ *
+ * ```typescript
+ * abstract class PaymentMethod {
+ *   @DiscriminatorKey()
+ *   method: string;
+ * }
+ *
+ * @DiscriminatorValue("credit_card")
+ * class CreditCard extends PaymentMethod {
+ *   @Property()
+ *   cardNumber: string;
+ *
+ *   @Property()
+ *   expiryDate: string;
+ * }
+ *
+ * @DiscriminatorValue("bank_transfer")
+ * class BankTransfer extends PaymentMethod {
+ *   @Property()
+ *   iban: string;
+ *
+ *   @Property()
+ *   bic: string;
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Polymorphic APIs**: Endpoints accepting multiple related types
+ * - **Event Systems**: Different event types with shared base structure
+ * - **Strategy Pattern**: Multiple implementation variants
+ * - **Type-Safe Deserialization**: Automatic instantiation of correct subclass
+ * - **OpenAPI Documentation**: Clear polymorphic type documentation
+ *
+ * ### Best Practices
+ *
+ * - Use on abstract base classes
+ * - Discriminator property should be required
+ * - Combine with `@DiscriminatorValue()` on subclasses
+ * - Use meaningful, stable discriminator values
+ * - Document discriminator values in API documentation
+ *
+ * ### Important Notes
+ *
+ * - Only one discriminator key per class hierarchy
+ * - The property is automatically marked with `@Property()`
+ * - All subclasses must have distinct `@DiscriminatorValue()` decorators
+ * - Discriminator values should be unique within the hierarchy
+ *
+ * @decorator
+ * @property
+ * @public
+ * @see DiscriminatorValue
+ */
 export declare function DiscriminatorKey(): PropertyDecorator;

package/lib/types/decorators/common/errorMsg.d.ts

@@ -1,6 +1,52 @@
 /**
- * Add an error message to the property.
+ * Adds custom error messages for validation failures using ajv-errors.
+ *
+ * The `@ErrorMsg()` decorator allows specifying custom error messages that override
+ * the default validation error messages. This requires the ajv-errors plugin to be
+ * configured with your AJV validator.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * class UserModel {
+ *   @ErrorMsg({ required: "Username is required" })
+ *   @Required()
+ *   username: string;
+ * }
+ * ```
+ *
+ * ### Multiple Validation Errors
+ *
+ * ```typescript
+ * class PasswordModel {
+ *   @ErrorMsg({
+ *     required: "Password is required",
+ *     minLength: "Password must be at least 8 characters",
+ *     pattern: "Password must contain letters and numbers"
+ *   })
+ *   @Required()
+ *   @MinLength(8)
+ *   @Pattern(/^(?=.*[A-Za-z])(?=.*\d)/)
+ *   password: string;
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **User-Friendly Messages**: Replace technical validation errors with clear messages
+ * - **Localization**: Provide translated error messages
+ * - **Business Context**: Add domain-specific error descriptions
+ * - **API Consistency**: Standardize error message formats
+ *
+ * ### Important Notes
+ *
+ * - Requires ajv-errors plugin to be installed and configured
+ * - Keys should match the validation keywords (required, minLength, etc.)
+ * - Messages are stored as custom schema keys
+ *
+ * @param obj - Object mapping validation keywords to custom error messages
+ *
  * @decorator
- * @ajv
+ * @public
  */
 export declare function ErrorMsg(obj: Record<string, string>): (...args: any[]) => any;

package/lib/types/decorators/common/example.d.ts

@@ -1,11 +1,73 @@
 /**
- * Add an example metadata on the decorated element.
+ * Adds example values to the schema for documentation purposes.
+ *
+ * The `@Example()` decorator provides sample values that appear in OpenAPI/Swagger
+ * documentation, helping API consumers understand expected data formats. Multiple
+ * examples can be provided, and they're displayed in API documentation tools.
+ *
+ * ### On Properties
+ *
+ * ```typescript
+ * class UserModel {
+ *   @Example("john.doe@example.com", "jane.smith@example.com")
+ *   email: string;
+ * }
+ * ```
+ *
+ * ### On Classes
+ *
+ * ```typescript
+ * @Example({ name: "John", age: 30 })
+ * @Example({ name: "Jane", age: 25 })
+ * class PersonModel {
+ *   @Property()
+ *   name: string;
+ *
+ *   @Property()
+ *   age: number;
+ * }
+ * ```
+ *
+ * ### Complex Objects
+ *
+ * ```typescript
+ * class OrderModel {
+ *   @Example(
+ *     { id: "ORD-123", total: 99.99, items: ["item1", "item2"] },
+ *     { id: "ORD-456", total: 149.99, items: ["item3"] }
+ *   )
+ *   orderData: object;
+ * }
+ * ```
+ *
+ * ### With Validation
+ *
+ * ```typescript
+ * class ProductModel {
+ *   @Example("Electronics", "Clothing", "Books")
+ *   @MinLength(3)
+ *   @MaxLength(50)
+ *   category: string;
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **API Documentation**: Show realistic example values
+ * - **Interactive Docs**: Populate try-it-out forms with examples
+ * - **Code Generation**: Provide samples for client SDK generation
+ * - **Testing**: Reference values for test cases
+ *
+ * ### Important Notes
+ *
+ * - Examples are for documentation only, not validation
+ * - Multiple examples can be provided
+ * - Examples should match the property's type and constraints
+ * - Appears in OpenAPI spec under `examples` field
+ *
+ * @param examples - One or more example values
  *
  * @decorator
- * @swagger
- * @schema
- * @input
- * @methodDecorator
- * @classDecorator
+ * @public
  */
 export declare function Example(...examples: any[]): Function;

package/lib/types/decorators/common/examples.d.ts

@@ -1,12 +1,105 @@
 import { OpenSpecHash, OpenSpecRef, OS3Example } from "@tsed/openspec";
 /**
- * Add a examples metadata on the decorated element.
+ * Adds named examples for parameters in OpenAPI 3.0 format.
+ *
+ * The `@Examples()` decorator provides named examples specifically for parameters,
+ * following the OpenAPI 3.0 specification format. Unlike `@Example()`, this accepts
+ * an object with named example entries, each with a value and optional description.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * @Controller("/users")
+ * class UserController {
+ *   @Get("/:id")
+ *   async getUser(
+ *     @Examples({
+ *       admin: {
+ *         value: "admin-123",
+ *         summary: "Admin user ID"
+ *       },
+ *       regular: {
+ *         value: "user-456",
+ *         summary: "Regular user ID"
+ *       }
+ *     })
+ *     @PathParams("id")
+ *     id: string
+ *   ) {}
+ * }
+ * ```
+ *
+ * ### Query Parameters
+ *
+ * ```typescript
+ * @Get("/search")
+ * async search(
+ *   @Examples({
+ *     simple: {
+ *       value: "typescript",
+ *       summary: "Simple keyword search"
+ *     },
+ *     complex: {
+ *       value: "typescript AND nodejs",
+ *       summary: "Boolean search query"
+ *     }
+ *   })
+ *   @QueryParams("q")
+ *   query: string
+ * ) {}
+ * ```
+ *
+ * ### With Descriptions
+ *
+ * ```typescript
+ * @Post("/filter")
+ * async filter(
+ *   @Examples({
+ *     basic: {
+ *       value: { status: "active" },
+ *       summary: "Filter by status",
+ *       description: "Returns only active records"
+ *     },
+ *     advanced: {
+ *       value: { status: "active", role: "admin" },
+ *       summary: "Complex filter",
+ *       description: "Combines multiple filter criteria"
+ *     }
+ *   })
+ *   @BodyParams()
+ *   filters: object
+ * ) {}
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Interactive Docs**: Provide multiple example scenarios in Swagger UI
+ * - **API Education**: Show different use cases with descriptions
+ * - **Testing**: Reference examples for integration tests
+ * - **Client Generation**: Provide varied examples for SDK documentation
+ *
+ * ### OpenAPI 3.0 Format
+ *
+ * Generates:
+ * ```json
+ * {
+ *   "examples": {
+ *     "admin": {
+ *       "value": "admin-123",
+ *       "summary": "Admin user ID"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### vs @Example
+ *
+ * - `@Examples()`: Named examples with summaries/descriptions (OpenAPI 3.0)
+ * - `@Example()`: Simple array of values
+ *
+ * @param examples - Object mapping names to example definitions
  *
  * @decorator
- * @swagger
- * @schema
- * @input
- * @methodDecorator
- * @classDecorator
+ * @public
  */
 export declare function Examples(examples: OpenSpecHash<OS3Example | OpenSpecRef>): ParameterDecorator;