@tsed/schema 8.19.2 → 8.19.3

package/lib/esm/constants/OperationVerbs.js

@@ -1,3 +1,23 @@
+/**
+ * HTTP and WebSocket operation verbs supported by Ts.ED.
+ *
+ * This enum defines all supported operation verbs for HTTP endpoints,
+ * WebSocket operations, and special routing cases. These verbs are used
+ * to define route handlers and generate OpenAPI specifications.
+ *
+ * ### HTTP Verbs
+ * Standard HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.) are supported
+ * for RESTful API operations.
+ *
+ * ### WebSocket Verbs
+ * PUBLISH and SUBSCRIBE are used for WebSocket operations and message patterns.
+ *
+ * ### Special Verbs
+ * - ALL: Matches all HTTP methods for a route
+ * - CUSTOM: Allows custom HTTP methods
+ *
+ * @public
+ */
 export var OperationVerbs;
 (function (OperationVerbs) {
     OperationVerbs["ALL"] = "ALL";
@@ -13,6 +33,14 @@ export var OperationVerbs;
     OperationVerbs["SUBSCRIBE"] = "SUBSCRIBE";
     OperationVerbs["CUSTOM"] = "CUSTOM";
 })(OperationVerbs || (OperationVerbs = {}));
+/**
+ * List of HTTP operation verbs including the special ALL and CUSTOM verbs.
+ *
+ * This array contains all HTTP methods supported for REST API operations,
+ * excluding WebSocket-specific verbs (PUBLISH, SUBSCRIBE).
+ *
+ * @public
+ */
 export const OPERATION_HTTP_VERBS = [
     OperationVerbs.ALL,
     OperationVerbs.GET,
@@ -25,4 +53,11 @@ export const OPERATION_HTTP_VERBS = [
     OperationVerbs.TRACE,
     OperationVerbs.CUSTOM
 ];
+/**
+ * List of WebSocket operation verbs for pub/sub messaging patterns.
+ *
+ * These verbs are used to define WebSocket message handlers in Ts.ED applications.
+ *
+ * @public
+ */
 export const OPERATION_WS_VERBS = [OperationVerbs.PUBLISH, OperationVerbs.SUBSCRIBE];

package/lib/esm/constants/VendorKeys.js

@@ -1,3 +1,32 @@
+/**
+ * Vendor extension keys used in JSON schemas and OpenAPI specifications.
+ *
+ * These keys are used as custom extension properties (prefixed with `x-` in OpenAPI)
+ * to store Ts.ED-specific metadata in generated schemas. Vendor extensions enable
+ * advanced features like generic type handling, group-based serialization, and
+ * nullable type support.
+ *
+ * ### Usage
+ *
+ * Vendor keys are automatically added to schemas by decorators and mappers.
+ * They preserve TypeScript type information and enable runtime schema transformations.
+ *
+ * ### Generic Type Keys
+ * - GENERIC_LABELS: Labels for generic type parameters
+ * - GENERIC_LABEL: Single generic type label
+ * - GENERIC_OF: Generic type reference
+ *
+ * ### Group Keys
+ * - GROUPS: Property group memberships
+ * - GROUPS_NAME: Named group identifier
+ * - FORWARD_GROUPS: Groups forwarded to nested properties
+ * - ALLOWED_GROUPS: Groups allowed for access
+ *
+ * ### Type Keys
+ * - NULLABLE: Marks a type as nullable
+ *
+ * @public
+ */
 export var VendorKeys;
 (function (VendorKeys) {
     VendorKeys["GENERIC_LABELS"] = "genericLabels";

package/lib/esm/constants/httpStatusMessages.js

@@ -1,5 +1,28 @@
 import { constantCase } from "change-case";
 import statuses from "statuses";
+/**
+ * Map of HTTP status codes to their human-readable labels and constant names.
+ *
+ * This constant provides a standardized lookup table for all HTTP status codes,
+ * mapping each code to both a descriptive label and a constant-case identifier.
+ * The mapping is generated from the standard HTTP status code definitions.
+ *
+ * ### Structure
+ *
+ * Each entry contains:
+ * - `label`: Human-readable status message (e.g., "Not Found")
+ * - `code`: Constant-case identifier (e.g., "NOT_FOUND")
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Access status information
+ * const status404 = HTTP_STATUS_MESSAGES["404"];
+ * // { label: "Not Found", code: "NOT_FOUND" }
+ * ```
+ *
+ * @public
+ */
 export const HTTP_STATUS_MESSAGES = statuses.codes.reduce((map, code) => {
     const message = String(statuses(code));
     return {
@@ -9,9 +32,45 @@ export const HTTP_STATUS_MESSAGES = statuses.codes.reduce((map, code) => {
 }, {});
 HTTP_STATUS_MESSAGES["200"].label = "Success";
 HTTP_STATUS_MESSAGES["200"].code = "SUCCESS";
+/**
+ * Get the constant-case identifier for an HTTP status code.
+ *
+ * Converts a status code to its constant representation (e.g., 404 → "NOT_FOUND").
+ * Useful for generating TypeScript constants and error codes.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const constant = getStatusConstant(404);
+ * // Returns: "NOT_FOUND"
+ * ```
+ *
+ * @param status - The HTTP status code (number or string)
+ * @returns The constant-case identifier, or undefined if not found
+ *
+ * @public
+ */
 export function getStatusConstant(status) {
     return HTTP_STATUS_MESSAGES[status]?.code;
 }
+/**
+ * Get the human-readable message for an HTTP status code.
+ *
+ * Returns the descriptive label associated with a status code
+ * (e.g., 404 → "Not Found").
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const message = getStatusMessage(404);
+ * // Returns: "Not Found"
+ * ```
+ *
+ * @param status - The HTTP status code (number or string)
+ * @returns The human-readable status message, or undefined if not found
+ *
+ * @public
+ */
 export function getStatusMessage(status) {
     return HTTP_STATUS_MESSAGES[status]?.label;
 }

package/lib/esm/constants/jsonSchemaProperties.js

@@ -1,8 +1,55 @@
+/**
+ * JSON Schema properties for composition keywords (oneOf, allOf, anyOf).
+ *
+ * These properties define schema composition, allowing multiple schemas to be
+ * combined using different logical operators.
+ *
+ * @public
+ */
 export const MANY_OF_PROPERTIES = ["oneOf", "allOf", "anyOf"];
+/**
+ * JSON Schema properties specific to string type validation.
+ *
+ * These properties control string length constraints, pattern matching,
+ * and format validation (e.g., email, uri, date-time).
+ *
+ * @public
+ */
 export const STRING_PROPERTIES = ["minLength", "maxLength", "pattern", "format"];
+/**
+ * JSON Schema properties specific to boolean type validation.
+ *
+ * Currently empty as boolean types have no specific validation properties
+ * beyond the type itself.
+ *
+ * @public
+ */
 export const BOOLEAN_PROPERTIES = [];
+/**
+ * JSON Schema properties specific to number and integer type validation.
+ *
+ * These properties control numeric range constraints and divisibility rules.
+ *
+ * @public
+ */
 export const NUMBER_PROPERTIES = ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"];
+/**
+ * JSON Schema properties specific to array type validation.
+ *
+ * These properties control array size constraints, uniqueness requirements,
+ * item schemas, and containment rules.
+ *
+ * @public
+ */
 export const ARRAY_PROPERTIES = ["maxItems", "minItems", "uniqueItems", "items", "contains", "maxContains", "minContains"];
+/**
+ * JSON Schema properties specific to object type validation.
+ *
+ * These properties control object property constraints, pattern-based properties,
+ * and property dependencies.
+ *
+ * @public
+ */
 export const OBJECT_PROPERTIES = [
     "maxItems",
     "minItems",
@@ -14,4 +61,12 @@ export const OBJECT_PROPERTIES = [
     "patternProperties",
     "dependencies"
 ];
+/**
+ * JSON Schema properties common to all types.
+ *
+ * These properties can be applied to any schema regardless of its type,
+ * defining constant values or enumerated options.
+ *
+ * @public
+ */
 export const COMMON_PROPERTIES = ["const", "enum"];

package/lib/esm/decorators/class/children.js

@@ -1,13 +1,101 @@
 import { Store } from "@tsed/core";
 import { JsonEntityFn } from "../common/jsonEntityFn.js";
 /**
- * Add Children class to compose routes
+ * Declares child controller classes for route composition and hierarchy.
+ *
+ * The `@Children()` decorator establishes parent-child relationships between controllers,
+ * allowing you to compose complex routing hierarchies and organize related endpoints into
+ * logical groups. Child controllers inherit the parent's base path.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * @Controller("/users")
+ * @Children(UserProfileController, UserSettingsController)
+ * class UserController {
+ *   @Get("/")
+ *   list() {
+ *     // GET /users/
+ *   }
+ * }
+ *
+ * @Controller("/profile")
+ * class UserProfileController {
+ *   @Get("/")
+ *   getProfile() {
+ *     // GET /users/profile/
+ *   }
+ * }
+ *
+ * @Controller("/settings")
+ * class UserSettingsController {
+ *   @Get("/")
+ *   getSettings() {
+ *     // GET /users/settings/
+ *   }
+ * }
+ * ```
+ *
+ * ### Multi-Level Hierarchy
+ *
+ * ```typescript
+ * @Controller("/api")
+ * @Children(UsersController, ProductsController)
+ * class ApiController {}
+ *
+ * @Controller("/users")
+ * @Children(UserProfileController, UserOrdersController)
+ * class UsersController {}
+ *
+ * @Controller("/profile")
+ * class UserProfileController {
+ *   @Get("/")
+ *   get() {
+ *     // GET /api/users/profile/
+ *   }
+ * }
+ * ```
+ *
+ * ### Resource Organization
+ *
+ * ```typescript
+ * @Controller("/admin")
+ * @Children(
+ *   AdminUsersController,
+ *   AdminProductsController,
+ *   AdminReportsController
+ * )
+ * class AdminController {
+ *   // Parent controller for all admin routes
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Route Organization**: Group related endpoints logically
+ * - **API Versioning**: Organize versions with child controllers
+ * - **Module Structure**: Mirror application module hierarchy in routes
+ * - **Access Control**: Apply middleware at parent level for all children
+ * - **Documentation**: Generate organized OpenAPI specs with grouped endpoints
+ *
+ * ### Benefits
+ *
+ * - **Maintainability**: Keep related routes together
+ * - **Scalability**: Easy to add new endpoint groups
+ * - **Clarity**: Clear route hierarchy in codebase
+ * - **Reusability**: Share middleware and configuration across children
+ *
+ * ### Important Notes
+ *
+ * - Children automatically inherit parent's base path
+ * - Parent-child relationship is stored in metadata
+ * - Useful for generating structured API documentation
+ * - Middleware on parent applies to all children
+ *
+ * @param children - Controller classes to register as children
  *
  * @decorator
- * @swagger
- * @schema
- * @classDecorator
- * @param children
+ * @public
  */
 export function Children(...children) {
     return JsonEntityFn((store) => {

package/lib/esm/decorators/class/discriminatorValue.js

@@ -1,45 +1,149 @@
 import { snakeCase } from "change-case";
 import { JsonEntityFn } from "../common/jsonEntityFn.js";
 /**
- * Declare a Discriminator value on a child class.
+ * Declares the discriminator value for a subclass in a polymorphic hierarchy.
  *
- * ```ts
- * export class Event {
- *   @DiscriminatorKey() // declare this property a discriminator key
+ * The `@DiscriminatorValue()` decorator specifies the value that should be present in the
+ * discriminator key property to identify this specific subclass. This is used together with
+ * `@DiscriminatorKey()` on the base class for proper polymorphic type resolution during
+ * serialization and deserialization.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * abstract class Event {
+ *   @DiscriminatorKey()
  *   type: string;
  *
  *   @Property()
- *   value: string;
+ *   timestamp: Date;
  * }
  *
  * @DiscriminatorValue("page_view")
- * export class PageView extends Event {
- *   @Required()
+ * class PageView extends Event {
+ *   @Property()
  *   url: string;
+ *
+ *   @Property()
+ *   referrer: string;
  * }
  *
  * @DiscriminatorValue("action")
- * export class Action extends Event {
- *   @Required()
- *   event: string;
+ * class Action extends Event {
+ *   @Property()
+ *   actionName: string;
+ *
+ *   @Property()
+ *   metadata: object;
  * }
+ * ```
  *
- * @DiscriminatorValue()
- * export class CustomAction extends Event {
- *   @Required()
- *   event: string;
+ * ### Auto-Generated Values
  *
+ * If no value is provided, it auto-generates from the class name in snake_case:
+ *
+ * ```typescript
+ * @DiscriminatorValue()  // Generates "custom_action"
+ * class CustomAction extends Event {
  *   @Property()
- *   meta: string;
+ *   customField: string;
  * }
  * ```
  *
+ * ### Multiple Values (Aliases)
+ *
+ * Support multiple discriminator values for the same class:
+ *
+ * ```typescript
+ * @DiscriminatorValue("click", "tap", "press")
+ * class ClickEvent extends Event {
+ *   // Matches when type is "click", "tap", OR "press"
+ * }
+ * ```
+ *
+ * ### Payment Methods Example
+ *
+ * ```typescript
+ * abstract class PaymentMethod {
+ *   @DiscriminatorKey()
+ *   type: string;
+ * }
+ *
+ * @DiscriminatorValue("credit_card")
+ * class CreditCardPayment extends PaymentMethod {
+ *   @Property()
+ *   cardNumber: string;
+ *
+ *   @Property()
+ *   cvv: string;
+ * }
+ *
+ * @DiscriminatorValue("paypal")
+ * class PayPalPayment extends PaymentMethod {
+ *   @Property()
+ *   email: string;
+ * }
+ *
+ * @DiscriminatorValue("bank_transfer")
+ * class BankTransfer extends PaymentMethod {
+ *   @Property()
+ *   iban: string;
+ * }
+ * ```
+ *
+ * ### With API Endpoints
+ *
+ * ```typescript
+ * @Post("/events")
+ * async trackEvent(@BodyParams() event: Event) {
+ *   // Framework automatically deserializes to correct subclass
+ *   // based on the 'type' field value in request body
+ *   if (event instanceof PageView) {
+ *     // Handle page view
+ *   } else if (event instanceof Action) {
+ *     // Handle action
+ *   }
+ * }
+ * ```
+ *
+ * ### OpenAPI Generation
+ *
+ * Generates proper discriminator mapping:
+ *
+ * ```json
+ * {
+ *   "discriminator": {
+ *     "propertyName": "type",
+ *     "mapping": {
+ *       "page_view": "#/components/schemas/PageView",
+ *       "action": "#/components/schemas/Action"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Event Systems**: Different event types with shared structure
+ * - **Payment Processing**: Multiple payment method types
+ * - **Notification Systems**: Various notification channels
+ * - **Content Types**: Polymorphic content (articles, videos, images)
+ * - **API Responses**: Different response formats based on type
+ *
+ * ### Important Notes
+ *
+ * - Must be used on subclasses that extend a class with `@DiscriminatorKey()`
+ * - Each subclass should have a unique discriminator value
+ * - If omitted, value is auto-generated from class name (snake_case)
+ * - Multiple values create aliases for backward compatibility
+ * - Works with OpenAPI discriminator specification
+ *
+ * @param value - The discriminator value (auto-generated if omitted)
+ * @param values - Additional alias values for this subclass
+ *
  * @decorator
- * @swagger
- * @schema
- * @classDecorator
- * @param value
- * @param values
+ * @public
+ * @see DiscriminatorKey
  */
 export function DiscriminatorValue(value, ...values) {
     return JsonEntityFn((store) => {

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

@@ -1,23 +1,104 @@
 import { CollectionOf } from "./collectionOf.js";
 /**
- * Set the type of the item collection. The possible value is String, Boolean, Number, Date, Object, Class, etc...
+ * Validates that an array contains at least one element matching the specified type/schema.
  *
- * The array instance will be valid against "contains" if at least one of its elements is valid against the given schema.
+ * The `@CollectionContains()` decorator uses JSON Schema's `contains` keyword to ensure
+ * that at least one item in the array is valid against the given schema. This is useful
+ * for validation where you need to guarantee certain elements exist in a collection
+ * without requiring all elements to match.
+ *
+ * ### Basic Usage
+ *
+ * ```typescript
+ * class SearchResults {
+ *   @CollectionContains(String)
+ *   tags: string[];
+ *   // Array must contain at least one string
+ * }
+ * ```
+ *
+ * ### With String Constraints
+ *
+ * ```typescript
+ * class ValidationModel {
+ *   @CollectionContains(String).MinLength(5).MaxLength(20)
+ *   keywords: string[];
+ *   // Must contain at least one string between 5-20 characters
+ * }
+ * ```
+ *
+ * ### With Custom Classes
  *
  * ```typescript
- * class Model {
- *    @CollectionContains(String).MinLength(0).MaxLength(0)
- *    property: string[];
+ * class AdminUser {
+ *   @Property()
+ *   role: string;
+ *
+ *   @Property()
+ *   permissions: string[];
+ * }
+ *
+ * class Team {
+ *   @CollectionContains(AdminUser)
+ *   members: User[];
+ *   // Team must contain at least one AdminUser
  * }
  * ```
  *
- * @param {Type<any>} type
+ * ### Mixed Type Arrays
+ *
+ * ```typescript
+ * class DataSet {
+ *   @CollectionContains(Number).Minimum(100)
+ *   values: (number | string)[];
+ *   // Must contain at least one number >= 100
+ * }
+ * ```
+ *
+ * ### Validation Behavior
+ *
+ * ```typescript
+ * @CollectionContains(String).MinLength(3)
+ * items: string[];
+ *
+ * // Valid:
+ * ["a", "abc", "b"]          // Contains "abc" with length >= 3
+ * ["hello", "world"]         // Both match, but only one needed
+ *
+ * // Invalid:
+ * ["a", "b", "c"]            // No string with length >= 3
+ * []                         // Empty array has no matching elements
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Required Elements**: Ensure specific items exist in collections
+ * - **Mixed Arrays**: Validate presence of certain types in heterogeneous arrays
+ * - **Quality Checks**: Guarantee minimum quality standards for at least one item
+ * - **Search Results**: Ensure relevant results exist in search responses
+ *
+ * ### Chaining with Other Validators
+ *
+ * ```typescript
+ * class ProductList {
+ *   @CollectionContains(String).MinLength(3)
+ *   @MinItems(1)
+ *   @MaxItems(10)
+ *   names: string[];
+ *   // 1-10 items, with at least one name having 3+ characters
+ * }
+ * ```
+ *
+ * ### vs CollectionOf
+ *
+ * - `@CollectionContains()`: At least **one** element must match the schema
+ * - `@CollectionOf()`: **All** elements must match the schema
+ *
+ * @param type - The type or class that at least one array element must match
+ *
  * @decorator
  * @validation
- * @swagger
- * @schema
- * @input
- * @collections
+ * @public
  */
 export function CollectionContains(type) {
     return CollectionOf(type).Contains();