@tsed/schema 8.19.2 → 8.19.3

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

@@ -2,47 +2,84 @@ import { withErrorMsg } from "../../utils/withErrorMsg.js";
 import { Allow } from "./allow.js";
 import { Optional } from "./optional.js";
 /**
- * Add required annotation on Property or Parameter.
+ * Mark a property or parameter as required.
  *
- * The @@Required@@ decorator can be used on two cases.
+ * The `@Required()` decorator enforces that a property must have a value during
+ * validation. It works on both model properties and method parameters, and triggers
+ * validation errors when values are `null`, `undefined`, or empty strings.
  *
- * To decorate a parameters:
+ * ### Usage on Properties
  *
  * ```typescript
- * @Post("/")
- * async method(@Required() @BodyParams("field") field: string) {}
+ * class User {
+ *   @Required()
+ *   @Property()
+ *   email: string;
+ *
+ *   @Required()
+ *   @Property()
+ *   name: string;
+ * }
  * ```
  *
- * To decorate a model:
+ * ### Usage on Parameters
+ *
+ * ```typescript
+ * @Controller("/users")
+ * class UserController {
+ *   @Post("/")
+ *   async create(@Required() @BodyParams() user: User) {
+ *     // user is required in request body
+ *   }
+ *
+ *   @Get("/:id")
+ *   async get(@Required() @PathParams("id") id: string) {
+ *     // id is required in path
+ *   }
+ * }
+ * ```
+ *
+ * ### Validation Behavior
+ *
+ * By default, `@Required()` rejects:
+ * - `null` values
+ * - `undefined` values
+ * - Empty strings (`""`)
+ *
+ * ### Allowing Specific Values
+ *
+ * Use `@Allow()` to permit specific values that would normally be rejected:
  *
  * ```typescript
  * class Model {
+ *   // Allow empty string but still mark as required
  *   @Required()
- *   field: string;
+ *   @Allow("")
+ *   optionalText: string;
+ *
+ *   // Allow null
+ *   @Required()
+ *   @Allow(null)
+ *   nullableField: string | null;
  * }
  * ```
  *
- * ::: tip
- * Required will throw a BadRequest when the given value is `null`, an empty string or `undefined`.
- * :::
+ * ### Making Optional
  *
- * ### Allow values
- *
- * In some case, you didn't want trigger a BadRequest when the value is an empty string for example.
- * The decorator `@Allow()`, allow you to configure a value list for which there will be no exception.
+ * To explicitly mark a property as optional:
  *
  * ```typescript
  * class Model {
- *   @Allow("") // add automatically required flag
- *   field: string;
+ *   @Required(false) // or use @Optional()
+ *   optionalField: string;
  * }
  * ```
  *
+ * @param required - Whether the property/parameter is required (default: true)
+ * @param allowedRequiredValues - Values to allow even when marked as required
+ *
  * @decorator
- * @validation
- * @swagger
- * @schema
- * @input
+ * @public
  */
 export const Required = withErrorMsg("required", (required = true, ...allowedRequiredValues) => {
     return required ? Allow(...allowedRequiredValues) : Optional();

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

@@ -1,13 +1,125 @@
 import { JsonEntityFn } from "./jsonEntityFn.js";
 /**
- * Set the property as WriteOnly.
+ * Marks a property as write-only, indicating it should not be included in responses.
+ *
+ * The `@WriteOnly()` decorator sets the `writeOnly` flag in the JSON Schema, which signals
+ * that this property should only appear in request payloads and be excluded from response
+ * data. This is commonly used for sensitive data like passwords that should be accepted
+ * as input but never returned to clients.
+ *
+ * ### Basic Usage - Passwords
+ *
+ * ```typescript
+ * class UserModel {
+ *   @Property()
+ *   username: string;
+ *   // Readable and writable
+ *
+ *   @WriteOnly()
+ *   password: string;
+ *   // Can be sent in requests but never returned in responses
+ * }
+ * ```
+ *
+ * ### Registration/Update Models
+ *
+ * ```typescript
+ * class UserRegistration {
+ *   @Property()
+ *   email: string;
+ *
+ *   @WriteOnly()
+ *   @MinLength(8)
+ *   password: string;
+ *
+ *   @WriteOnly()
+ *   passwordConfirmation: string;
+ *   // Only needed for validation, never stored or returned
+ * }
+ * ```
+ *
+ * ### Sensitive Configuration
+ *
+ * ```typescript
+ * class ApiKeyConfig {
+ *   @Property()
+ *   name: string;
+ *
+ *   @WriteOnly()
+ *   apiKey: string;
+ *   // Accept key in requests, but don't expose it in responses
+ *
+ *   @ReadOnly()
+ *   createdAt: Date;
+ *   // Only in responses
+ * }
+ * ```
+ *
+ * ### Toggle Write-Only
+ *
+ * ```typescript
+ * class SecureModel {
+ *   @WriteOnly(true)
+ *   secret: string;
+ *   // Write-only
+ *
+ *   @WriteOnly(false)
+ *   publicField: string;
+ *   // Explicitly not write-only (default behavior)
+ * }
+ * ```
+ *
+ * ### OpenAPI Behavior
+ *
+ * In OpenAPI/Swagger documentation:
+ * - Write-only properties appear in **request** schemas
+ * - Write-only properties are **excluded** from **response** schemas
+ * - Helps document sensitive fields that shouldn't be returned
+ *
+ * ### vs ReadOnly
+ *
+ * - `@WriteOnly()`: Property can be written but not read (requests only)
+ * - `@ReadOnly()`: Property can be read but not written (responses only)
+ * - Neither: Property can be both read and written
+ *
+ * ### Common Use Cases
+ *
+ * - **Passwords**: Authentication credentials that should never be exposed
+ * - **Secret Keys**: API keys, tokens, or other sensitive credentials
+ * - **Confirmation Fields**: Password confirmation, email confirmation
+ * - **Temporary Inputs**: Fields used only for processing, not storage
+ * - **Security Tokens**: CSRF tokens or one-time codes
+ *
+ * ### Security Best Practices
+ *
+ * ```typescript
+ * class ChangePassword {
+ *   @WriteOnly()
+ *   @MinLength(8)
+ *   currentPassword: string;
+ *
+ *   @WriteOnly()
+ *   @MinLength(8)
+ *   newPassword: string;
+ *
+ *   @WriteOnly()
+ *   newPasswordConfirmation: string;
+ *   // All password fields are write-only
+ * }
+ * ```
+ *
+ * ### Important Notes
+ *
+ * - `@WriteOnly()` is a schema hint for documentation and client validation
+ * - Server-side code must still explicitly exclude these fields from responses
+ * - Use serialization groups or DTOs to ensure write-only fields aren't leaked
+ * - Always hash/encrypt sensitive data before storage
+ *
+ * @param writeOnly - Whether the property is write-only (default: true)
  *
- * @returns {Function}
  * @decorator
  * @validation
- * @property
- * @parameter
- * @schema
+ * @public
  */
 export function WriteOnly(writeOnly = true) {
     return JsonEntityFn((store) => {

package/lib/esm/domain/JsonClassStore.js

@@ -3,6 +3,81 @@ import { DecoratorTypes } from "@tsed/core";
 import { JsonEntityComponent } from "../decorators/config/jsonEntityComponent.js";
 import { JsonEntityStore } from "./JsonEntityStore.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Store for class-level metadata and schema information.
+ *
+ * JsonClassStore manages metadata for classes decorated with schema decorators like
+ * `@Model()`, `@Generics()`, `@DiscriminatorKey()`, etc. It serves as the root container
+ * for all class-level schema information and coordinates child stores for properties
+ * and methods.
+ *
+ * ### Responsibilities
+ *
+ * - **Schema Generation**: Creates and maintains the JsonSchema for the class
+ * - **Children Coordination**: Manages child PropertyStore and MethodStore instances
+ * - **Route Configuration**: Stores base path for controller classes
+ * - **Inheritance**: Handles schema inheritance from parent classes
+ * - **OpenAPI Integration**: Generates component schemas for OpenAPI specifications
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Get class store
+ * const classStore = JsonEntityStore.from(MyClass);
+ *
+ * // Access class schema
+ * const schema = classStore.schema;
+ *
+ * // Get all properties
+ * const properties = classStore.children;
+ *
+ * // Check if it's a controller with a path
+ * const path = classStore.path;
+ * ```
+ *
+ * ### Class Store Hierarchy
+ *
+ * The class store acts as the root of the store hierarchy:
+ * ```
+ * JsonClassStore (User class)
+ * ├─ JsonPropertyStore (name property)
+ * ├─ JsonPropertyStore (email property)
+ * └─ JsonMethodStore (validate method)
+ *    ├─ JsonParameterStore (param 0)
+ *    └─ JsonParameterStore (param 1)
+ * ```
+ *
+ * ### Schema Structure
+ *
+ * For a class like:
+ * ```typescript
+ * class User {
+ *   @Property()
+ *   name: string;
+ *
+ *   @Property()
+ *   email: string;
+ * }
+ * ```
+ *
+ * The class store generates:
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "name": {"type": "string"},
+ *     "email": {"type": "string"}
+ *   }
+ * }
+ * ```
+ *
+ * ### Controller Path
+ *
+ * For controller classes decorated with `@Controller("/users")`, the store
+ * maintains the base path which is used for route generation.
+ *
+ * @public
+ */
 let JsonClassStore = class JsonClassStore extends JsonEntityStore {
     constructor() {
         super(...arguments);

package/lib/esm/domain/JsonDiscriminator.js

@@ -1,4 +1,61 @@
 import { cleanObject } from "@tsed/core";
+/**
+ * Manages discriminator mappings for polymorphic type resolution.
+ *
+ * A discriminator enables polymorphism in schemas by using a specific property
+ * value to determine which subtype schema to apply. This is essential for
+ * inheritance hierarchies and union types in OpenAPI specifications.
+ *
+ * ### Concept
+ *
+ * When a base class has multiple derived classes, the discriminator property
+ * (e.g., "type", "kind") indicates which concrete class an object represents.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Base class
+ * @DiscriminatorKey("type")
+ * abstract class Animal {
+ *   type: string;
+ * }
+ *
+ * // Derived classes
+ * @DiscriminatorValue("dog")
+ * class Dog extends Animal {
+ *   breed: string;
+ * }
+ *
+ * @DiscriminatorValue("cat")
+ * class Cat extends Animal {
+ *   indoor: boolean;
+ * }
+ * ```
+ *
+ * ### OpenAPI Mapping
+ *
+ * Generates OpenAPI discriminator objects:
+ * ```json
+ * {
+ *   "discriminator": {
+ *     "propertyName": "type",
+ *     "mapping": {
+ *       "dog": "#/components/schemas/Dog",
+ *       "cat": "#/components/schemas/Cat"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Type Mapping**: Maps discriminator values to TypeScript classes
+ * - **Bidirectional Lookup**: Find type by value or values by type
+ * - **Default Values**: Get the default discriminator value for a type
+ * - **Children Discovery**: List all derived types
+ *
+ * @public
+ */
 export class Discriminator {
     constructor({ base, propertyName, types, values } = {}) {
         this.values = new Map();

package/lib/esm/domain/JsonEntityStore.js

@@ -3,6 +3,52 @@ import { ancestorsOf, classOf, decoratorTypeOf, descriptorOf, isArrayOrArrayClas
  * @ignore
  */
 export const JsonEntitiesContainer = new Map();
+/**
+ * Base class for storing metadata about decorated entities (classes, properties, methods, parameters).
+ *
+ * JsonEntityStore is the foundation of Ts.ED's metadata system, managing schema information
+ * and type metadata for decorated entities. It serves as the parent class for specialized
+ * stores (JsonClassStore, JsonPropertyStore, JsonMethodStore, JsonParameterStore).
+ *
+ * ### Entity Types
+ *
+ * Different decorator types create different store subclasses:
+ * - **Class decorators**: Create JsonClassStore instances
+ * - **Property decorators**: Create JsonPropertyStore instances
+ * - **Method decorators**: Create JsonMethodStore instances
+ * - **Parameter decorators**: Create JsonParameterStore instances
+ *
+ * ### Key Responsibilities
+ *
+ * - **Schema Management**: Each store maintains a JsonSchema for the decorated entity
+ * - **Type Resolution**: Resolves TypeScript types, including collections and generics
+ * - **Metadata Storage**: Stores decorator metadata using Ts.ED's Store system
+ * - **Inheritance**: Manages parent-child relationships between entities
+ *
+ * ### Usage
+ *
+ * Stores are typically accessed via static `from()` methods:
+ *
+ * ```typescript
+ * // Get store for a class
+ * const classStore = JsonEntityStore.from(MyClass);
+ *
+ * // Get store for a property
+ * const propStore = JsonEntityStore.from(MyClass, "propertyName");
+ *
+ * // Get store for a method parameter
+ * const paramStore = JsonEntityStore.from(MyClass, "methodName", 0);
+ * ```
+ *
+ * ### Architecture
+ *
+ * The store system creates a hierarchical structure:
+ * - ClassStore contains PropertyStore and MethodStore children
+ * - MethodStore contains ParameterStore children
+ * - Each store has an associated JsonSchema
+ *
+ * @public
+ */
 export class JsonEntityStore {
     constructor(options) {
         this.isStore = true;

package/lib/esm/domain/JsonFormatTypes.js

@@ -1,3 +1,42 @@
+/**
+ * Standard JSON Schema format types for string validation.
+ *
+ * These format types provide semantic validation for string values beyond basic
+ * pattern matching. They are part of the JSON Schema specification and widely
+ * supported by validation libraries.
+ *
+ * ### Date and Time Formats
+ * - **DATE_TIME**: RFC 3339 date-time (e.g., "2024-01-15T10:30:00Z")
+ * - **DATE**: RFC 3339 full-date (e.g., "2024-01-15")
+ * - **TIME**: RFC 3339 full-time (e.g., "10:30:00")
+ *
+ * ### Network Formats
+ * - **EMAIL**: Email address (RFC 5322)
+ * - **HOSTNAME**: Internet hostname (RFC 1123)
+ * - **IPV4**: IPv4 address
+ * - **IPV6**: IPv6 address
+ * - **URI**: Uniform Resource Identifier (RFC 3986)
+ * - **URL**: URL variant of URI
+ * - **URI_REF**: URI reference
+ * - **URI_TEMPLATE**: URI template (RFC 6570)
+ *
+ * ### Other Formats
+ * - **JSON_POINTER**: JSON Pointer (RFC 6901)
+ * - **RELATIVE_JSON_POINTER**: Relative JSON Pointer
+ * - **UUID**: Universally Unique Identifier (RFC 4122)
+ * - **REGEX**: Regular expression (ECMA-262)
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {JsonFormatTypes} from "@tsed/schema";
+ *
+ * schema.format(JsonFormatTypes.EMAIL);
+ * schema.format(JsonFormatTypes.DATE_TIME);
+ * ```
+ *
+ * @public
+ */
 export var JsonFormatTypes;
 (function (JsonFormatTypes) {
     JsonFormatTypes["DATE_TIME"] = "date-time";

package/lib/esm/domain/JsonLazyRef.js

@@ -1,5 +1,38 @@
 import { nameOf } from "@tsed/core";
 import { getJsonEntityStore } from "../utils/getJsonEntityStore.js";
+/**
+ * Lazy reference to a schema type for handling circular dependencies.
+ *
+ * JsonLazyRef provides a deferred reference mechanism for types that may not be
+ * available at decoration time due to circular dependencies or forward references.
+ * The actual type is resolved lazily when needed, avoiding initialization order issues.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * class User {
+ *   @Property()
+ *   name: string;
+ *
+ *   // Circular reference - user has a manager who is also a user
+ *   @Property()
+ *   manager: User; // Internally uses lazy ref
+ * }
+ * ```
+ *
+ * ### Use Cases
+ *
+ * - **Circular Dependencies**: Classes that reference themselves or each other
+ * - **Forward References**: References to classes defined later in the file
+ * - **Conditional Imports**: Types that may not be available immediately
+ *
+ * ### How It Works
+ *
+ * The lazy ref wraps a function that returns the type, delaying type resolution
+ * until the schema is actually needed during schema generation.
+ *
+ * @public
+ */
 export class JsonLazyRef {
     constructor(getType) {
         this.getType = getType;

package/lib/esm/domain/JsonMap.js

@@ -1,5 +1,37 @@
 import { isFunction } from "@tsed/core";
 import { execMapper } from "../registries/JsonSchemaMapperContainer.js";
+/**
+ * Base class for JSON document representations using a Map structure.
+ *
+ * JsonMap provides a Map-based foundation for storing and manipulating JSON-compatible
+ * data structures. It extends the native Map with additional features for assignment,
+ * serialization, and mapper integration.
+ *
+ * This class serves as the base for many Ts.ED schema classes including JsonOperation,
+ * JsonParameter, JsonResponse, and JsonRequestBody.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * class MyJsonDoc extends JsonMap<{name: string; value: number}> {
+ *   // Custom methods
+ * }
+ *
+ * const doc = new MyJsonDoc({name: "test", value: 42});
+ * const json = doc.toJSON();
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Map Interface**: Full Map API support for key-value operations
+ * - **Fluent Assignment**: Assign multiple properties via object
+ * - **Serialization**: Convert to plain JSON via mapper system
+ * - **Type Safety**: Generic type parameter for stored values
+ *
+ * @typeParam T - The shape of the object this map represents
+ *
+ * @public
+ */
 export class JsonMap extends Map {
     constructor(obj = {}) {
         super();

package/lib/esm/domain/JsonMedia.js

@@ -1,6 +1,34 @@
 import { isArray, isClass } from "@tsed/core";
 import { JsonMap } from "./JsonMap.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Represents a media type definition for HTTP request or response bodies.
+ *
+ * JsonMedia encapsulates the schema and examples for a specific media type
+ * (e.g., "application/json", "application/xml") in OpenAPI specifications.
+ * It provides methods to configure the schema and examples for the media type.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const media = new JsonMedia();
+ * media.type(User);
+ * media.examples({
+ *   user1: {
+ *     value: {name: "John", email: "john@example.com"}
+ *   }
+ * });
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Schema Definition**: Associated JSON schema for validation
+ * - **Examples**: Request/response examples for documentation
+ * - **Type Handling**: Automatic schema generation from TypeScript types
+ * - **Union Types**: Support for oneOf schemas with multiple types
+ *
+ * @public
+ */
 export class JsonMedia extends JsonMap {
     constructor(obj = {}) {
         super(obj);

package/lib/esm/domain/JsonMethodStore.js

@@ -5,6 +5,62 @@ import { isSuccessStatus } from "../utils/isSuccessStatus.js";
 import { JsonEntityStore } from "./JsonEntityStore.js";
 import { JsonOperation } from "./JsonOperation.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Store for method metadata, operations, and parameter information.
+ *
+ * JsonMethodStore manages metadata for controller methods decorated with operation
+ * decorators like `@Get()`, `@Post()`, `@Returns()`, etc. It maintains the JsonOperation
+ * for OpenAPI generation and coordinates method parameters.
+ *
+ * ### Responsibilities
+ *
+ * - **Operation Management**: Maintains JsonOperation for OpenAPI spec generation
+ * - **Parameter Coordination**: Manages child JsonParameterStore instances
+ * - **Middleware Configuration**: Handles before/after/use middleware registration
+ * - **Response Configuration**: Manages return types and status codes
+ * - **Route Information**: Stores HTTP methods, paths, and route metadata
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Get method store
+ * const methodStore = JsonEntityStore.from(MyController, "myMethod");
+ *
+ * // Access operation for OpenAPI
+ * const operation = methodStore.operation;
+ *
+ * // Get parameters
+ * const params = methodStore.parameters;
+ *
+ * // Check response type
+ * const returnType = methodStore.type;
+ * ```
+ *
+ * ### Operation Structure
+ *
+ * Each method store contains a JsonOperation that includes:
+ * - HTTP method and path information
+ * - Request parameters (path, query, body, headers)
+ * - Response definitions by status code
+ * - Security requirements
+ * - Tags and metadata
+ *
+ * ### Parameter Management
+ *
+ * The store maintains parameter metadata:
+ * - Parameters stored in `children` map by index
+ * - Accessible via `parameters` or `params` getters
+ * - Each parameter has its own JsonParameterStore
+ *
+ * ### Middleware Integration
+ *
+ * Supports three middleware phases:
+ * - **before**: Execute before the method
+ * - **use**: Execute as main middleware
+ * - **after**: Execute after the method
+ *
+ * @public
+ */
 let JsonMethodStore = class JsonMethodStore extends JsonEntityStore {
     constructor(options) {
         super({