@tsed/schema 8.19.1 → 8.19.3

package/lib/types/domain/JsonOperation.d.ts

@@ -4,6 +4,15 @@ import { JsonMap } from "./JsonMap.js";
 import { JsonParameter } from "./JsonParameter.js";
 import { JsonResponse } from "./JsonResponse.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Represents an HTTP operation path with metadata for OpenAPI specifications.
+ *
+ * This class associates an HTTP method and path with operation-level metadata
+ * such as summary and description. It's used internally to manage routing
+ * information for API endpoints.
+ *
+ * @public
+ */
 export declare class JsonMethodPath extends JsonMap<any> {
     method: string;
     path: string | RegExp;
@@ -11,10 +20,52 @@ export declare class JsonMethodPath extends JsonMap<any> {
     summary(summary: string): this;
     description(description: string): this;
 }
+/**
+ * Configuration options for JSON operations compatible with OpenAPI 3 specifications.
+ *
+ * Extends the OpenAPI 3 operation specification with Ts.ED-specific media type
+ * declarations (consumes/produces) for request and response handling.
+ *
+ * @public
+ */
 export interface JsonOperationOptions extends OS3Operation<JsonSchema, JsonParameter, JsonMap<JsonResponse>> {
     consumes: string[];
     produces: string[];
 }
+/**
+ * Represents an HTTP operation (endpoint) with complete OpenAPI metadata.
+ *
+ * JsonOperation is the core class for defining HTTP endpoints in Ts.ED, storing all
+ * operation-level information required for OpenAPI specification generation including:
+ *
+ * - Request parameters (path, query, header, body)
+ * - Response definitions with status codes
+ * - Security requirements
+ * - Tags and categorization
+ * - Media type handling (consumes/produces)
+ * - Operation metadata (summary, description, operationId)
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const operation = new JsonOperation()
+ *   .summary("Create a user")
+ *   .description("Creates a new user in the system")
+ *   .addTags([{name: "Users"}])
+ *   .addParameter(0, parameterMetadata)
+ *   .addResponse(201, responseMetadata);
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Parameters**: Manage operation parameters by index or name
+ * - **Responses**: Define responses for different HTTP status codes
+ * - **Security**: Configure authentication and authorization
+ * - **Media Types**: Specify accepted and produced content types
+ * - **Routing**: Multiple path/method combinations per operation
+ *
+ * @public
+ */
 export declare class JsonOperation extends JsonMap<JsonOperationOptions> {
     #private;
     $kind: string;

package/lib/types/domain/JsonOperationPathsMap.d.ts

@@ -1,4 +1,42 @@
 import { JsonMethodPath } from "./JsonOperation.js";
+/**
+ * Map container for storing HTTP operation paths indexed by method and path.
+ *
+ * JsonOperationPathsMap maintains a collection of operation paths (HTTP method + URL path
+ * combinations) for a controller. It provides efficient lookup and prevents duplicate
+ * operations from being registered.
+ *
+ * ### Key Features
+ *
+ * - **Unique Keys**: Stores operations using `method-path` composite keys
+ * - **Method Safety**: Ensures operations are uniquely identified
+ * - **Efficient Lookup**: Fast retrieval of operations by method and path
+ * - **Type Safety**: Extends Map with JsonMethodPath values
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const pathsMap = new JsonOperationPathsMap();
+ *
+ * // Add operation path
+ * const methodPath = { method: "GET", path: "/users" };
+ * pathsMap.setOperationPath(methodPath);
+ *
+ * // Retrieve by composite key
+ * const operation = pathsMap.get("GET-/users");
+ * ```
+ *
+ * ### Key Generation
+ *
+ * The map uses a composite key format: `{method}-{path}`
+ * - Example: `"GET-/users/:id"` for a GET operation on `/users/:id`
+ * - Example: `"POST-/users"` for a POST operation on `/users`
+ *
+ * This ensures that different HTTP methods on the same path are treated as
+ * distinct operations.
+ *
+ * @public
+ */
 export declare class JsonOperationPathsMap extends Map<string, JsonMethodPath> {
     $kind: string;
     readonly $isJsonDocument = true;

package/lib/types/domain/JsonOperationRoute.d.ts

@@ -1,6 +1,60 @@
 import { Type } from "@tsed/core";
 import { JsonMethodStore } from "./JsonMethodStore.js";
 import { JsonMethodPath, JsonOperation } from "./JsonOperation.js";
+/**
+ * Represents a fully resolved HTTP route combining controller and method metadata.
+ *
+ * JsonOperationRoute provides a unified view of an HTTP endpoint by combining:
+ * - Controller class information (token, basePath)
+ * - Method metadata (endpoint store)
+ * - Operation details (HTTP method, path, parameters)
+ * - Full URL computation
+ *
+ * ### Responsibilities
+ *
+ * - **URL Resolution**: Combines base path and operation path into full URL
+ * - **Metadata Access**: Provides convenient access to operation, parameters, and store
+ * - **Route Identification**: Computes route names and operation IDs
+ * - **Parameter Type Tracking**: Maintains map of parameter types (query, body, etc.)
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Routes are typically created during framework initialization
+ * const route = new JsonOperationRoute({
+ *   token: MyController,
+ *   endpoint: methodStore,
+ *   operationPath: { method: "GET", path: "/:id" },
+ *   basePath: "/users"
+ * });
+ *
+ * // Access route information
+ * console.log(route.fullPath);  // "/users/:id"
+ * console.log(route.method);     // "GET"
+ * console.log(route.name);       // "MyController.getUser()"
+ * console.log(route.operationId); // "getUser"
+ * ```
+ *
+ * ### URL Construction
+ *
+ * The route combines controller base path with operation path:
+ * - Base path: `/users` (from `@Controller("/users")`)
+ * - Operation path: `/:id` (from `@Get("/:id")`)
+ * - Full path: `/users/:id`
+ *
+ * ### Parameter Type Detection
+ *
+ * The route maintains a map of parameter types present in the operation:
+ * ```typescript
+ * route.has("query")  // true if operation has @QueryParams
+ * route.has("body")   // true if operation has @BodyParams
+ * route.has("path")   // true if operation has @PathParams
+ * ```
+ *
+ * @typeParam Entity - The type of JsonMethodStore (default: JsonMethodStore)
+ *
+ * @public
+ */
 export declare class JsonOperationRoute<Entity extends JsonMethodStore = JsonMethodStore> {
     readonly token: Type<any>;
     readonly endpoint: Entity;

package/lib/types/domain/JsonParameter.d.ts

@@ -2,6 +2,41 @@ import { OpenSpecHash, OpenSpecRef, OS3Example, OS3Parameter } from "@tsed/opens
 import { JsonSchemaOptions } from "../interfaces/JsonSchemaOptions.js";
 import { JsonMap } from "./JsonMap.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Represents an HTTP operation parameter for OpenAPI specifications.
+ *
+ * JsonParameter defines a single parameter for an HTTP operation, supporting
+ * various parameter locations (path, query, header, body, files) and providing
+ * a fluent API for building parameter metadata compatible with OpenAPI 3.
+ *
+ * ### Parameter Types
+ *
+ * - **path**: Parameter in the URL path (e.g., `/users/{id}`)
+ * - **query**: Query string parameter (e.g., `?page=1`)
+ * - **header**: HTTP header parameter
+ * - **body**: Request body parameter
+ * - **files**: File upload parameter
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const param = new JsonParameter()
+ *   .name("userId")
+ *   .in("path")
+ *   .required(true)
+ *   .description("The user identifier")
+ *   .schema(JsonSchema.from(String));
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Schema Integration**: Associated JSON schema for validation
+ * - **Examples**: Support for parameter examples
+ * - **Expression**: Custom parameter expressions for complex bindings
+ * - **Validation**: Required/optional flags and schema constraints
+ *
+ * @public
+ */
 export declare class JsonParameter extends JsonMap<OS3Parameter<JsonSchema>> {
     $kind: string;
     expression: string;

package/lib/types/domain/JsonParameterStore.d.ts

@@ -2,14 +2,111 @@ import { Type } from "@tsed/core";
 import { JsonEntityStore, JsonEntityStoreOptions } from "./JsonEntityStore.js";
 import type { JsonMethodStore } from "./JsonMethodStore.js";
 import { JsonParameter } from "./JsonParameter.js";
+/**
+ * Configuration options for creating a JsonParameterStore.
+ *
+ * @public
+ */
 export interface JsonParameterStoreOptions extends JsonEntityStoreOptions {
     dataPath?: string;
     paramType?: string;
     expression?: string;
 }
+/**
+ * Interface for pipe classes that transform parameter values.
+ *
+ * Pipes are called by the framework to transform or validate parameter values
+ * before they reach the method handler.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * class ParseIntPipe implements PipeMethods<string, number> {
+ *   transform(value: string, metadata: JsonParameterStore): number {
+ *     return parseInt(value, 10);
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T - The input type
+ * @typeParam R - The output type after transformation
+ *
+ * @public
+ */
 export interface PipeMethods<T = any, R = any> {
     transform(value: T, metadata: JsonParameterStore): R;
 }
+/**
+ * Store for method parameter metadata and schema information.
+ *
+ * JsonParameterStore manages metadata for method parameters decorated with decorators
+ * like `@BodyParams()`, `@PathParams()`, `@QueryParams()`, etc. It handles parameter
+ * validation, transformation pipes, and OpenAPI parameter generation.
+ *
+ * ### Responsibilities
+ *
+ * - **Parameter Definition**: Maintains JsonParameter for OpenAPI spec generation
+ * - **Type Resolution**: Resolves parameter types from TypeScript metadata
+ * - **Validation**: Manages required/optional state and validation rules
+ * - **Transformation**: Coordinates pipe execution for value transformation
+ * - **Location Tracking**: Stores where the parameter comes from (path, query, body, etc.)
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Get parameter store
+ * const paramStore = JsonParameterStore.get(MyController, "myMethod", 0);
+ *
+ * // Access parameter definition
+ * const parameter = paramStore.parameter;
+ *
+ * // Check if required
+ * const isRequired = paramStore.required;
+ *
+ * // Get all parameters for a method
+ * const params = JsonParameterStore.getParams(MyController, "myMethod");
+ * ```
+ *
+ * ### Parameter Types
+ *
+ * Parameters can come from different locations:
+ * - **path**: URL path parameters (`/users/:id`)
+ * - **query**: Query string parameters (`?page=1`)
+ * - **body**: Request body
+ * - **header**: HTTP headers
+ * - **cookies**: Cookie values
+ * - **files**: File uploads
+ *
+ * ### Validation
+ *
+ * The store provides validation helpers:
+ * - `required`: Marks parameter as required
+ * - `allowedRequiredValues`: Values that bypass required check
+ * - `isRequired(value)`: Checks if a value satisfies required constraint
+ *
+ * ### Transformation Pipes
+ *
+ * Parameters can have transformation pipes that process values:
+ * ```typescript
+ * @Controller("/")
+ * class MyController {
+ *   @Get("/:id")
+ *   get(@PathParams("id") @UsePipe(ParseIntPipe) id: number) {
+ *     // id is automatically transformed to number
+ *   }
+ * }
+ * ```
+ *
+ * ### Expression Binding
+ *
+ * Parameters can use expressions to extract nested values:
+ * ```typescript
+ * @BodyParams("user.address.city") city: string
+ * // Extracts: request.body.user.address.city
+ * ```
+ *
+ * @public
+ */
 export declare class JsonParameterStore extends JsonEntityStore {
     paramType: string;
     expression: string;

package/lib/types/domain/JsonParameterTypes.d.ts

@@ -1,3 +1,29 @@
+/**
+ * HTTP operation parameter location types.
+ *
+ * This enum defines where parameters can be located in an HTTP request.
+ * These types are used for both JSON Schema and OpenAPI parameter definitions.
+ *
+ * ### Parameter Locations
+ *
+ * - **BODY**: Request body parameter (payload)
+ * - **PATH**: URL path parameter (e.g., `/users/{id}`)
+ * - **QUERY**: URL query string parameter (e.g., `?page=1`)
+ * - **HEADER**: HTTP header parameter (e.g., `Authorization`)
+ * - **COOKIES**: Cookie parameter
+ * - **FILES**: File upload parameter (multipart/form-data)
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {JsonParameterTypes} from "@tsed/schema";
+ *
+ * parameter.in(JsonParameterTypes.QUERY);
+ * parameter.in(JsonParameterTypes.PATH);
+ * ```
+ *
+ * @public
+ */
 export declare enum JsonParameterTypes {
     BODY = "body",
     PATH = "path",

package/lib/types/domain/JsonPropertyStore.d.ts

@@ -1,6 +1,50 @@
 import { Type } from "@tsed/core";
 import type { JsonClassStore } from "./JsonClassStore.js";
 import { JsonEntityStore } from "./JsonEntityStore.js";
+/**
+ * Store for property metadata and schema information.
+ *
+ * JsonPropertyStore manages metadata for class properties decorated with schema decorators
+ * like `@Property()`, `@Required()`, `@MinLength()`, etc. It handles schema generation,
+ * type resolution, and integration with the parent class schema.
+ *
+ * ### Responsibilities
+ *
+ * - **Schema Generation**: Creates and maintains the JsonSchema for the property
+ * - **Type Resolution**: Resolves property types including primitives, classes, and collections
+ * - **Parent Integration**: Registers the property schema with the parent class schema
+ * - **Collection Handling**: Special handling for arrays, Sets, Maps, and other collections
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Get property store
+ * const propertyStore = JsonPropertyStore.get(MyClass, "propertyName");
+ *
+ * // Access property schema
+ * const schema = propertyStore.schema;
+ *
+ * // Check property type
+ * const type = propertyStore.type;
+ * const isCollection = propertyStore.isCollection;
+ * ```
+ *
+ * ### Schema Integration
+ *
+ * When a property is decorated, this store:
+ * 1. Resolves the property's TypeScript type
+ * 2. Creates an appropriate JsonSchema
+ * 3. Registers it in the parent class's `properties` object
+ * 4. Handles collection item schemas for arrays/collections
+ *
+ * ### Type Handling
+ *
+ * - **Primitives**: Creates schema with appropriate type (string, number, boolean, etc.)
+ * - **Classes**: Creates object schema with reference to the class schema
+ * - **Collections**: Creates array schema with item type schema
+ *
+ * @public
+ */
 export declare class JsonPropertyStore extends JsonEntityStore {
     readonly parent: JsonClassStore;
     static get(target: Type<any>, propertyKey: string | symbol): JsonPropertyStore;

package/lib/types/domain/JsonRequestBody.d.ts

@@ -1,7 +1,38 @@
 import { OpenSpecHash, OS3MediaType, OS3RequestBody } from "@tsed/openspec";
 import { JsonMap } from "./JsonMap.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Configuration options for HTTP request body definitions compatible with OpenAPI 3.
+ *
+ * @public
+ */
 export type JsonRequestBodyOptions = OS3RequestBody<JsonSchema>;
+/**
+ * Represents an HTTP request body definition for OpenAPI specifications.
+ *
+ * JsonRequestBody defines the structure and content types accepted by an HTTP
+ * operation's request body. It provides a fluent API for specifying request
+ * body schemas, media types, and examples.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const requestBody = new JsonRequestBody()
+ *   .description("User creation payload")
+ *   .addContent("application/json", userSchema, {
+ *     example1: {name: "John", email: "john@example.com"}
+ *   });
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Content Types**: Support for multiple media types (JSON, XML, form data, etc.)
+ * - **Schema Integration**: JSON schemas for request validation
+ * - **Examples**: Request body examples for documentation
+ * - **Required Flag**: Mark request body as required or optional
+ *
+ * @public
+ */
 export declare class JsonRequestBody extends JsonMap<JsonRequestBodyOptions> {
     $kind: string;
     constructor(obj?: Partial<JsonRequestBodyOptions>);

package/lib/types/domain/JsonResponse.d.ts

@@ -3,7 +3,41 @@ import { JsonHeader } from "../interfaces/JsonOpenSpec.js";
 import { JsonMap } from "./JsonMap.js";
 import { JsonMedia } from "./JsonMedia.js";
 import { JsonSchema } from "./JsonSchema.js";
+/**
+ * Configuration options for HTTP response definitions compatible with OpenAPI 3.
+ *
+ * @public
+ */
 export type JsonResponseOptions = OS3Response<JsonSchema, string | JsonHeader>;
+/**
+ * Represents an HTTP response definition for OpenAPI specifications.
+ *
+ * JsonResponse defines the structure of an HTTP response including status code,
+ * description, headers, and content types. It provides a fluent API for building
+ * response metadata compatible with OpenAPI 3 specifications.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const response = new JsonResponse()
+ *   .description("User created successfully")
+ *   .headers({"X-Rate-Limit": "100"})
+ *   .content({
+ *     "application/json": {
+ *       schema: userSchema
+ *     }
+ *   });
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Status Codes**: Associated HTTP status code
+ * - **Headers**: Response header definitions
+ * - **Content Types**: Multiple media type support
+ * - **Schema Integration**: JSON schemas for response bodies
+ *
+ * @public
+ */
 export declare class JsonResponse extends JsonMap<JsonResponseOptions> {
     $kind: string;
     status: number;