@tsed/schema 8.19.1 → 8.19.3

package/lib/esm/fn/string.js

@@ -1,10 +1,50 @@
 import { from } from "./from.js";
 /**
- * Declare a new string model.
+ * Create a string schema programmatically.
  *
- * See @@JsonSchema@@ to discover available methods.
+ * This function provides a fluent API for building string schemas without decorators.
+ * It returns a JsonSchema instance configured for string type, which can be further
+ * customized with validation constraints, formats, and other JSON Schema properties.
  *
- * @schemaFunctional
+ * ### Usage
+ *
+ * ```typescript
+ * import {string} from "@tsed/schema";
+ *
+ * // Basic string schema
+ * const nameSchema = string();
+ *
+ * // String with constraints
+ * const emailSchema = string()
+ *   .format("email")
+ *   .minLength(5)
+ *   .maxLength(100)
+ *   .description("User email address");
+ *
+ * // String with pattern
+ * const phoneSchema = string()
+ *   .pattern(/^\d{3}-\d{3}-\d{4}$/)
+ *   .description("Phone number in format: 123-456-7890");
+ *
+ * // Enum string
+ * const statusSchema = string()
+ *   .enum("active", "inactive", "pending");
+ * ```
+ *
+ * ### Available Methods
+ *
+ * The returned JsonSchema provides many chainable methods:
+ * - `minLength(n)` / `maxLength(n)` - Length constraints
+ * - `pattern(regex)` - Pattern matching
+ * - `format(type)` - Format validation (email, uri, date-time, etc.)
+ * - `enum(...values)` - Restrict to specific values
+ * - `description(text)` - Add description
+ * - `default(value)` - Set default value
+ * - `nullable()` - Allow null values
+ *
+ * @returns A new JsonSchema configured as a string type
+ *
+ * @public
  */
 export function string() {
     return from(String);

package/lib/types/constants/OperationVerbs.d.ts

@@ -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 declare enum OperationVerbs {
     ALL = "ALL",// special key
     GET = "GET",
@@ -12,5 +32,20 @@ export declare enum OperationVerbs {
     SUBSCRIBE = "SUBSCRIBE",
     CUSTOM = "CUSTOM"
 }
+/**
+ * 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 declare const OPERATION_HTTP_VERBS: OperationVerbs[];
+/**
+ * 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 declare const OPERATION_WS_VERBS: OperationVerbs[];

package/lib/types/constants/VendorKeys.d.ts

@@ -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 declare enum VendorKeys {
     GENERIC_LABELS = "genericLabels",
     GENERIC_LABEL = "genericLabel",

package/lib/types/constants/httpStatusMessages.d.ts

@@ -1,3 +1,26 @@
+/**
+ * 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 declare const HTTP_STATUS_MESSAGES: {
     [x: string]: {
         label: string;
@@ -7,5 +30,41 @@ export declare const HTTP_STATUS_MESSAGES: {
         code: string;
     };
 };
+/**
+ * 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 declare function getStatusConstant(status: number | string): any;
+/**
+ * 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 declare function getStatusMessage(status: number | string): any;

package/lib/types/constants/jsonSchemaProperties.d.ts

@@ -1,7 +1,62 @@
+/**
+ * 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 declare const MANY_OF_PROPERTIES: string[];
+/**
+ * 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 declare const STRING_PROPERTIES: string[];
+/**
+ * JSON Schema properties specific to boolean type validation.
+ *
+ * Currently empty as boolean types have no specific validation properties
+ * beyond the type itself.
+ *
+ * @public
+ */
 export declare const BOOLEAN_PROPERTIES: never[];
+/**
+ * JSON Schema properties specific to number and integer type validation.
+ *
+ * These properties control numeric range constraints and divisibility rules.
+ *
+ * @public
+ */
 export declare const NUMBER_PROPERTIES: string[];
+/**
+ * JSON Schema properties specific to array type validation.
+ *
+ * These properties control array size constraints, uniqueness requirements,
+ * item schemas, and containment rules.
+ *
+ * @public
+ */
 export declare const ARRAY_PROPERTIES: string[];
+/**
+ * JSON Schema properties specific to object type validation.
+ *
+ * These properties control object property constraints, pattern-based properties,
+ * and property dependencies.
+ *
+ * @public
+ */
 export declare const OBJECT_PROPERTIES: string[];
+/**
+ * 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 declare const COMMON_PROPERTIES: string[];

package/lib/types/decorators/class/children.d.ts

@@ -1,11 +1,99 @@
 import { Type } from "@tsed/core";
 /**
- * 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 declare function Children(...children: Type<any>[]): ClassDecorator;

package/lib/types/decorators/class/discriminatorValue.d.ts

@@ -1,42 +1,146 @@
 /**
- * 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 declare function DiscriminatorValue(value?: string, ...values: string[]): ClassDecorator;

package/lib/types/decorators/collections/collectionContains.d.ts

@@ -1,21 +1,102 @@
 /**
- * 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 declare function CollectionContains(type: any): import("./collectionOf.js").CollectionOfChainedDecorators;