@tsed/schema 6.88.1 → 6.89.0

package/lib/types/decorators/operations/returns.d.ts

@@ -0,0 +1,238 @@
+import { Type } from "@tsed/core";
+import { OS3Example } from "@tsed/openspec";
+import { JsonSchema, JsonSchemaObject } from "../../domain/JsonSchema";
+import { JsonHeader, JsonHeaders } from "../../interfaces/JsonOpenSpec";
+import { GenericValue } from "../../utils/generics";
+export interface ReturnsChainedDecorators {
+    <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void;
+    (target: Function): void;
+    /**
+     * Set a Content-Type for the current response
+     * @param value
+     * @constructor
+     */
+    ContentType(value: string): this;
+    /**
+     * Add a description
+     * @param description
+     */
+    Description(description: string): this;
+    /**
+     * Add examples
+     * @param examples
+     */
+    Examples(examples: Record<string, OS3Example>): this;
+    Examples(examples: Record<string, any>): this;
+    Examples(examples: any): this;
+    /**
+     * Change the model type
+     * @param type
+     */
+    Type(type: Type<any> | any): this;
+    /**
+     * Change the status
+     * @param status
+     * @constructor
+     */
+    Status(status: string | number): this;
+    /**
+     * Add the nested types
+     * @param types
+     */
+    Of(...types: GenericValue[]): this;
+    /**
+     * Declare a nested generic models
+     * @param generics
+     */
+    Nested(...generics: GenericValue[]): this;
+    /**
+     * Add header.
+     * @param key
+     * @param value
+     */
+    Header(key: string, value: number | string | (JsonHeader & {
+        value?: string | number | boolean;
+    })): this;
+    /**
+     * Add headers
+     */
+    Headers(headers: JsonHeaders): this;
+    /**
+     * Add location hea
+     */
+    Location(location: string, meta?: JsonHeader): this;
+    /**
+     * Assign partial schema
+     * @param schema
+     */
+    Schema(schema: Partial<JsonSchemaObject> | JsonSchema): this;
+    /**
+     * Add an inline title for the return model.
+     * @param title
+     */
+    Title(title: string): this;
+    /**
+     *
+     * @param groups
+     * @constructor
+     */
+    Groups(...groups: string[]): this;
+    [key: string]: any;
+}
+/**
+ * Add responses documentation for a specific status code.
+ *
+ * ## Usage
+ *
+ * Ts.ED v5/v6 API introducing the chaining decorator concept. Now a decorator like Returns can be used with another decorators like Description.
+ *
+ * ::: warning
+ * v5 has a basic support of the chaining decorator to facilitate the migration to v6!
+ * :::
+ *
+ * ```typescript
+ * import {Returns} from "@tsed/schema";
+ *
+ * @Controller("/")
+ * class MyController {
+ *   @Returns(404, String).Description("Not Found")
+ *   @Returns(200, Model).Description("Success")
+ *   async myMethod(): Promise<Model> {}
+ * }
+ * ```
+ *
+ * ::: tip
+ * TypeScript and your IDE will discover automatically the chained decorators. But for more details you can look on @@ReturnsChainedDecorators@@ interface, to know
+ * what chained decorators are available under Returns decorator.
+ * :::
+ *
+ * This example will produce this documentation in swagger:
+ *
+ * ```json
+ * {
+ *   "responses": {
+ *     "404": {
+ *       "description": "Description",
+ *       "schema": {"type": "string"}
+ *     },
+ *     "2OO": {
+ *       "description": "Description",
+ *       "schema": {"$ref": "..."}
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Declaring an Array
+ *
+ * Use chained decorators to declare an array with model as following:
+ *
+ * ```typescript
+ * import {Returns} from "@tsed/schema";
+ *
+ * @Controller("/models")
+ * class ModelCtrl {
+ *   @Get("/")
+ *   @Returns(200, Array).Of(Model).Description("Success")
+ *   async myMethod(): Promise<Model>  {
+ *   }
+ * }
+ * ```
+ *
+ * Deprecated version:
+ *
+ * ```typescript
+ * import {ReturnsArray} from "@tsed/common";
+ * import {Returns} from "@tsed/schema";
+ *
+ * @Controller("/")
+ * class MyController {
+ *   @ReturnsArray(200, Model) // deprecated
+ *   async myMethod(): Promise<Model> {}
+ * }
+ * ```
+ *
+ * ### Declaring a generic model <Badge text="6+"/>
+ *
+ * Sometime, it might be useful to use generic models. TypeScript doesn't store the generic type in the metadata. This is why we need to
+ * declare explicitly the generic models with the decorators.
+ *
+ * One of the generic's usage, can be a paginated list. With Returns decorator it's now possible to declare generic type and generate the appropriate OpenSpec documentation.
+ *
+ * Starting with the pagination model, by using @@Generics@@ and @@CollectionOf@@:
+ *
+ * ```typescript
+ * @Generics("T")
+ * class Pagination<T> {
+ *  @CollectionOf("T")
+ *  data: T[];
+ *
+ *  @Property()
+ *  totalCount: number;
+ * }
+ * ```
+ *
+ * Now, we need a model to be used with the generic Pagination model:
+ *
+ * ```typescript
+ * class Product {
+ *  @Property()
+ *  id: string;
+ *
+ *  @Property()
+ *  title: string;
+ * }
+ * ```
+ *
+ * Finally, we can use our models on a method as following:
+ *
+ * ```typescript
+ * class Controller {
+ *   @OperationPath("POST", "/")
+ *   @Returns(200, Pagination).Of(Product).Description("description")
+ *   async method(): Promise<Pagination<Product> | null> {
+ *     return null;
+ *   }
+ * }
+ * ```
+ *
+ * ### Declaring a nested generics models <Badge text="6+"/>
+ *
+ * It's also possible to declare a nested generics models in order to have this type `Pagination<Submission<Product>>`:
+ *
+ * ```typescript
+ * import {Generics, Property, Returns} from "@tsed/schema";
+ * import {Post} from "@tsed/common";
+ *
+ * class Controller {
+ *   @Post("/")
+ *   @Returns(200, Pagination).Of(Submission).Nested(Product).Description("description")
+ *   async method(): Promise<Pagination<Submission<Product>> | null> {
+ *     return null;
+ *   }
+ * }
+ * ```
+ *
+ * And here is the Submission model:
+ *
+ * ```typescript
+ * import {Generics, Property} from "@tsed/schema";
+ *
+ * @Generics("T")
+ * class Submission<T> {
+ *   @Property()
+ *   _id: string;
+ *   @Property("T")
+ *   data: T;
+ * }
+ * ```
+ *
+ * @param status
+ * @param model
+ * @decorator
+ * @swagger
+ * @schema
+ * @response
+ * @operation
+ */
+export declare function Returns(status?: string | number, model?: Type<any>): ReturnsChainedDecorators;

package/lib/types/decorators/operations/route.d.ts

@@ -0,0 +1,185 @@
+import { OperationMethods } from "../../constants/httpMethods";
+export interface RouteChainedDecorators {
+    <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void;
+    /**
+     * @param string
+     * @constructor
+     */
+    Path(string: string): this;
+    /**
+     * Set the operation method
+     * @param method
+     */
+    Method(method: OperationMethods | string): this;
+    /**
+     * Set the operation id
+     * @param id
+     */
+    Id(id: string): this;
+    /**
+     * Set the operation id
+     * @param name
+     */
+    Name(name: string): this;
+    /**
+     *
+     * @param description
+     */
+    Description(description: string): this;
+    /**
+     * Summary
+     * @constructor
+     * @param Summary
+     */
+    Summary(Summary: string): this;
+}
+/**
+ * Describe a new route with a method and path.
+ *
+ * ```typescript
+ * @Controller('/')
+ * export class Ctrl {
+ *
+ *    @Route('GET', '/')
+ *    get() { }
+ * }
+ *
+ * ```
+ *
+ * @returns {Function}
+ * @param method
+ * @param path
+ * @param args
+ * @decorator
+ * @operation
+ */
+export declare function Route(method: string, path: string, ...args: any[]): RouteChainedDecorators;
+export declare function Route(...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function All(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Get(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Post(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Put(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Delete(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Head(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Patch(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;
+/**
+ * This method is just like the `router.METHOD()` methods, except that it matches all HTTP methods (verbs).
+ *
+ * This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches.
+ * For example, if you placed the following route at the top of all other route definitions, it would require that
+ * all routes from that point on would require authentication, and automatically load a user.
+ * Keep in mind that these callbacks do not have to act as end points; loadUser can perform a task, then call next()
+ * to continue matching subsequent routes.
+ * @param path
+ * @param args
+ * @returns {Function}
+ * @decorator
+ * @operation
+ * @httpMethod
+ */
+export declare function Options(path?: string | RegExp | any, ...args: any[]): RouteChainedDecorators;

package/lib/types/decorators/operations/security.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Add security metadata on the decorated method.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * @Controller("/")
+ * class ModelCtrl {
+ *    @Security("write:calendars")
+ *    async method() {}
+ * }
+ * ```
+ *
+ * @param name
+ * @param scopes
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export declare function Security(name: string, ...scopes: string[]): (...args: any[]) => any;

package/lib/types/decorators/operations/status.d.ts

@@ -0,0 +1,127 @@
+import { Type } from "@tsed/core";
+import { ReturnsChainedDecorators } from "./returns";
+/**
+ * Add responses documentation for a specific status code.
+ *
+ * ## Usage
+ *
+ * Ts.ED v6 API introducing the chaining decorator concept.
+ * Now a decorator like Returns can be used with another decorators like Description.
+ *
+ * ```typescript
+ * import {Returns} from "@tsed/schema";
+ *
+ * @Controller("/")
+ * class MyController {
+ *   @Status(404, String).Description("Not Found")
+ *   @Status(200, Model).Description("Success")
+ *   async myMethod(): Promise<Model> {}
+ * }
+ * ```
+ *
+ * ::: tip
+ * TypeScript and your IDE will discover automatically the chained decorators. But for more details you can look on @@ReturnsChainedDecorators@@ interface, to know
+ * what chained decorators are available under Returns decorator.
+ * :::
+ *
+ * This example will produce this documentation in swagger:
+ *
+ * ```json
+ * {
+ *   "responses": {
+ *     "404": {
+ *       "description": "Description",
+ *       "schema": {"type": "string"}
+ *     },
+ *     "2OO": {
+ *       "description": "Description",
+ *       "schema": {"$ref": "..."}
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Declaring a generic model
+ *
+ * Sometime, it might be useful to use generic models. TypeScript doesn't store the generic type in the metadata. This is why we need to
+ * declare explicitly the generic models with the decorators.
+ *
+ * One of the generic's usage, can be a paginated list. With Returns decorator it's now possible to declare generic type and generate the appropriate OpenSpec documentation.
+ *
+ * Starting with the pagination model, by using @@Generics@@ and @@CollectionOf@@:
+ *
+ * ```typescript
+ * @Generics("T")
+ * class Pagination<T> {
+ *  @CollectionOf("T")
+ *  data: T[];
+ *
+ *  @Property()
+ *  totalCount: number;
+ * }
+ * ```
+ *
+ * Now, we need a model to be used with the generic Pagination model:
+ *
+ * ```typescript
+ * class Product {
+ *  @Property()
+ *  id: string;
+ *
+ *  @Property()
+ *  title: string;
+ * }
+ * ```
+ *
+ * Finally, we can use our models on a method as following:
+ *
+ * ```typescript
+ * class Controller {
+ *   @OperationPath("POST", "/")
+ *   @Status(200, Pagination).Of(Product).Description("description")
+ *   async method(): Promise<Pagination<Product> | null> {
+ *     return null;
+ *   }
+ * }
+ * ```
+ *
+ * ### Declaring a nested generics models <Badge text="6+"/>
+ *
+ * It's also possible to declare a nested generics models in order to have this type `Pagination<Submission<Product>>`:
+ *
+ * ```typescript
+ * import {Generics, Property, Returns} from "@tsed/schema";
+ * import {Post} from "@tsed/common";
+ *
+ * class Controller {
+ *   @Post("/")
+ *   @Status(200, Pagination).Of(Submission).Nested(Product).Description("description")
+ *   async method(): Promise<Pagination<Submission<Product>> | null> {
+ *     return null;
+ *   }
+ * }
+ * ```
+ *
+ * And here is the Submission model:
+ *
+ * ```typescript
+ * import {Generics, Property} from "@tsed/schema";
+ *
+ * @Generics("T")
+ * class Submission<T> {
+ *   @Property()
+ *   _id: string;
+ *   @Property("T")
+ *   data: T;
+ * }
+ * ```
+ *
+ * @param status
+ * @param model
+ * @decorator
+ * @swagger
+ * @schema
+ * @response
+ * @operation
+ */
+export declare function Status(status: string | number, model?: Type<any> | any): ReturnsChainedDecorators;

package/lib/types/decorators/operations/summary.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Add summary metadata on the decorated element.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * class Model {
+ *    @Summary("summary")
+ *    id: string;
+ * }
+ * ```
+ *
+ * @param summary
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export declare function Summary(summary: string): (...args: any[]) => any;

package/lib/types/decorators/operations/tags.d.ts

@@ -0,0 +1,23 @@
+import { OpenSpecTag } from "@tsed/openspec";
+/**
+ * Add tags metadata on the decorated element.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * @Controller("/")
+ * class MyController {
+ *  @Tags("api")
+ *  get() {}
+ * }
+ * ```
+ *
+ * @param tags
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export declare function Tags(...tags: (string | OpenSpecTag)[]): (...args: any[]) => any;

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

@@ -0,0 +1,28 @@
+import { DecoratorParameters, DecoratorTypes } from "@tsed/core";
+import { JsonEntityStore } from "./JsonEntityStore";
+/**
+ * @ignore
+ */
+export interface DecoratorActionHandler {
+    (ctx: Map<string, any>): void;
+}
+/**
+ * @ignore
+ */
+export declare abstract class DecoratorContext<T = any> extends Map<string, any> {
+    readonly methods: string[];
+    protected decoratorType: DecoratorTypes;
+    protected entity: JsonEntityStore;
+    protected actions: DecoratorActionHandler[];
+    constructor(opts?: any);
+    addAction(cb: DecoratorActionHandler): this;
+    build(): T;
+    toObject(): any;
+    getMergedKey(key: string, defaultValue: any): any;
+    protected bind(args: DecoratorParameters, decorator: any): void;
+    protected onInit(args: DecoratorParameters, decorator: any): void;
+    protected onMapKey(key: string, value: any): void;
+    protected runActions(): this;
+    protected beforeInit(): void;
+    protected afterInit(): void;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @ignore
+ */
+export declare type AliasType = string | number | symbol;
+/**
+ * @ignore
+ */
+export declare type AliasMap = Map<AliasType, AliasType>;
+/**
+ * @ignore
+ */
+export declare function mapAliasedProperties(value: any, alias: AliasMap): any;

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

@@ -0,0 +1,12 @@
+import type { JsonMethodStore } from "./JsonMethodStore";
+import type { JsonPropertyStore } from "./JsonPropertyStore";
+import { JsonEntityStore } from "./JsonEntityStore";
+export declare class JsonClassStore extends JsonEntityStore {
+    /**
+     * List of children JsonEntityStore (properties or methods or params)
+     */
+    readonly children: Map<string | number, JsonMethodStore | JsonPropertyStore>;
+    get path(): string;
+    set path(path: string);
+    protected build(): void;
+}