@tsed/schema 8.19.1 → 8.19.3

package/lib/esm/domain/JsonOperation.js

@@ -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 class JsonMethodPath extends JsonMap {
     constructor(method, path) {
         super();
@@ -19,6 +28,40 @@ export class JsonMethodPath extends JsonMap {
         return this;
     }
 }
+/**
+ * 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 class JsonOperation extends JsonMap {
     #status;
     #redirection;

package/lib/esm/domain/JsonOperationPathsMap.js

@@ -1,3 +1,41 @@
+/**
+ * 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 class JsonOperationPathsMap extends Map {
     constructor() {
         super(...arguments);

package/lib/esm/domain/JsonOperationRoute.js

@@ -1,4 +1,58 @@
 import { concatPath } from "../utils/concatPath.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 class JsonOperationRoute {
     constructor(options) {
         Object.assign(this, options);

package/lib/esm/domain/JsonParameter.js

@@ -2,6 +2,41 @@ import { execMapper } from "../registries/JsonSchemaMapperContainer.js";
 import { JsonMap } from "./JsonMap.js";
 import { formatParameterType } from "./JsonParameterTypes.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 class JsonParameter extends JsonMap {
     constructor(obj = {}) {
         super(obj);

package/lib/esm/domain/JsonParameterStore.js

@@ -3,6 +3,77 @@ import { ancestorsOf, DecoratorTypes, isClass, isMethodDescriptor, Metadata, pro
 import { JsonEntityComponent } from "../decorators/config/jsonEntityComponent.js";
 import { JsonEntityStore } from "./JsonEntityStore.js";
 import { JsonParameter } from "./JsonParameter.js";
+/**
+ * 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
+ */
 let JsonParameterStore = class JsonParameterStore extends JsonEntityStore {
     constructor(options) {
         super(options);

package/lib/esm/domain/JsonParameterTypes.js

@@ -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 var JsonParameterTypes;
 (function (JsonParameterTypes) {
     JsonParameterTypes["BODY"] = "body";

package/lib/esm/domain/JsonPropertyStore.js

@@ -3,6 +3,50 @@ import { DecoratorTypes, isClass, Metadata, prototypeOf } from "@tsed/core";
 import { JsonEntityComponent } from "../decorators/config/jsonEntityComponent.js";
 import { JsonEntityStore } from "./JsonEntityStore.js";
 import { JsonSchema } from "./JsonSchema.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
+ */
 let JsonPropertyStore = class JsonPropertyStore extends JsonEntityStore {
     constructor() {
         super(...arguments);

package/lib/esm/domain/JsonRequestBody.js

@@ -1,5 +1,31 @@
 import { toJsonMapCollection } from "../utils/toJsonMapCollection.js";
 import { JsonMap } from "./JsonMap.js";
+/**
+ * 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 class JsonRequestBody extends JsonMap {
     constructor(obj = {}) {
         super(obj);

package/lib/esm/domain/JsonResponse.js

@@ -2,6 +2,35 @@ import { mapHeaders } from "../utils/mapHeaders.js";
 import { toJsonMapCollection } from "../utils/toJsonMapCollection.js";
 import { JsonMap } from "./JsonMap.js";
 import { JsonMedia } from "./JsonMedia.js";
+/**
+ * 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 class JsonResponse extends JsonMap {
     constructor(obj = {}) {
         super(obj);