@tsed/schema 6.88.1 → 6.89.0

package/lib/types/decorators/common/required.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Add required annotation on Property or Parameter.
+ *
+ * The @@Required@@ decorator can be used on two cases.
+ *
+ * To decorate a parameters:
+ *
+ * ```typescript
+ * @Post("/")
+ * async method(@Required() @BodyParams("field") field: string) {}
+ * ```
+ *
+ * To decorate a model:
+ *
+ * ```typescript
+ * class Model {
+ *   @Required()
+ *   field: string;
+ * }
+ * ```
+ *
+ * ::: tip
+ * Required will throw a BadRequest when the given value is `null`, an empty string or `undefined`.
+ * :::
+ *
+ * ### 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.
+ *
+ * ```typescript
+ * class Model {
+ *   @Allow("") // add automatically required flag
+ *   field: string;
+ * }
+ * ```
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export declare function Required(required?: boolean, ...allowedRequiredValues: any[]): any;

package/lib/types/decorators/common/requiredGroups.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Apply groups validation strategy for required property.
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export declare function RequiredGroups(...groups: string[]): Function;

package/lib/types/decorators/common/schema.d.ts

@@ -0,0 +1,53 @@
+import { JsonSchema, JsonSchemaObject } from "../../domain/JsonSchema";
+import { SpecTypes } from "../../domain/SpecTypes";
+/**
+ * Write data formatted to JsonSchema.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * @Schema({title: "test"})
+ * class Model {
+ *    @Schema({formatMinimum: "1987-10-24"})
+ *    @Format("date")
+ *    birthDate: Date
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "title": "test",
+ *   "properties": {
+ *     "birthdate": {
+ *        "type": "string",
+ *        "format": "date",
+ *        "formatMinimum": "1987-10-24"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param partialSchema
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export declare function Schema(partialSchema: Partial<JsonSchemaObject> | JsonSchema): (...args: any[]) => any;
+/**
+ * Apply specific schema depending on the spec version
+ * @param specType
+ * @param schema
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export declare function For(specType: SpecTypes, schema: any): (...args: any[]) => any;

package/lib/types/decorators/common/title.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Add title metadata on the decorated element.
+ *
+ * ::: warning
+ * For v6 user, use @@Title@@ from @tsed/schema instead of @tsed/common.
+ * :::
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @Title("title")
+ *    id: string;
+ * }
+ * ```
+ *
+ * Will produce:
+ *
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "id": {
+ *        "type": "string",
+ *        "title": "title"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param {string} title
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @input
+ */
+export declare function Title(title: string): (...args: any[]) => any;

package/lib/types/decorators/common/writeOnly.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Set the property as WriteOnly.
+ *
+ * @returns {Function}
+ * @decorator
+ * @validation
+ * @property
+ * @parameter
+ * @schema
+ */
+export declare function WriteOnly(writeOnly?: boolean): (...args: any[]) => any;

package/lib/types/decorators/config/jsonEntityComponent.d.ts

@@ -0,0 +1,10 @@
+import { DecoratorTypes, Type } from "@tsed/core";
+import { JsonEntityStore } from "../../domain/JsonEntityStore";
+/**
+ * Declare a new JsonEntityStore class for a specific decorator type.
+ *
+ * @ignore
+ * @param type
+ * @decorator
+ */
+export declare function JsonEntityComponent(type: DecoratorTypes): (target: Type<JsonEntityStore>) => void;

package/lib/types/decorators/generics/genericOf.d.ts

@@ -0,0 +1,76 @@
+import { GenericValue } from "../../utils/generics";
+export interface GenericOfChainedDecorators {
+    (...args: any): any;
+    /**
+     * Declare a nested generic models
+     * @param generics
+     */
+    Nested(...generics: GenericValue[]): this;
+}
+/**
+ * Set the types of a Generic class.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Product {
+ *   @Property()
+ *   label: string;
+ * }
+ *
+ * @Generics("T")
+ * class Paginated<T> {
+ *   @CollectionOf("T")
+ *   data: T[];
+ *
+ *   @Property()
+ *   totalCount: number;
+ * }
+ *
+ * class Payload {
+ *    @GenericOf(Product)
+ *    products: Paginated<Product>;
+ * }
+ * ```
+ *
+ * ## Example with nested generics
+ *
+ * ```typescript
+ * class Product {
+ *   @Property()
+ *   label: string;
+ * }
+ *
+ * @Generics("T")
+ * class Paginated<T> {
+ *   @CollectionOf("T")
+ *   data: T[];
+ *
+ *   @Property()
+ *   totalCount: number;
+ * }
+ *
+ * @Generics("D")
+ * class Submission<D> {
+ *   @Property()
+ *   _id: string;
+ *
+ *   @Property("D")
+ *   data: D;
+ * }
+ *
+ * class Payload {
+ *    @GenericOf(Submissions).Nested(Product)
+ *    submissions: Paginated<Submission<Product>>;
+ * }
+ * ```
+ *
+ * @param {Type<any>[]} generics
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @generics
+ */
+export declare function GenericOf(...generics: GenericValue[]): GenericOfChainedDecorators;

package/lib/types/decorators/generics/generics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Define generics list. This list is used by @@GenericOf@@ and the @@getJsonSchema@@ function to build the correct JsonSchema.
+ *
+ * See @@GenericOf@@ decorator for more details.
+ *
+ * @param generics
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ * @generics
+ */
+export declare function Generics(...generics: string[]): (target: any) => void;

package/lib/types/decorators/index.d.ts

@@ -0,0 +1,67 @@
+export * from "./class/children";
+export * from "./collections/collectionContains";
+export * from "./collections/collectionOf";
+export * from "./collections/maxItems";
+export * from "./collections/minItems";
+export * from "./collections/uniqueItems";
+export * from "./collections/maxProperties";
+export * from "./collections/minProperties";
+export * from "./generics/generics";
+export * from "./generics/genericOf";
+export * from "./operations/deprecated";
+export * from "./operations/consumes";
+export * from "./operations/contentType";
+export * from "./operations/in";
+export * from "./operations/operationId";
+export * from "./operations/operationPath";
+export * from "./operations/path";
+export * from "./operations/produces";
+export * from "./operations/returns";
+export * from "./operations/status";
+export * from "./operations/header";
+export * from "./operations/security";
+export * from "./operations/tags";
+export * from "./operations/summary";
+export * from "./operations/partial";
+export * from "./operations/redirect";
+export * from "./operations/location";
+export * from "./operations/route";
+export * from "./common/additionalProperties";
+export * from "./common/allow";
+export * from "./common/any";
+export * from "./common/integer";
+export * from "./common/const";
+export * from "./common/default";
+export * from "./common/description";
+export * from "./common/example";
+export * from "./common/examples";
+export * from "./common/enum";
+export * from "./common/exclusiveMaximum";
+export * from "./common/exclusiveMinimum";
+export * from "./common/format";
+export * from "./common/forwardGroups";
+export * from "./common/groups";
+export * from "./common/pattern";
+export * from "./common/ignore";
+export * from "./common/maximum";
+export * from "./common/maxLength";
+export * from "./common/minimum";
+export * from "./common/minLength";
+export * from "./common/multipleOf";
+export * from "./common/name";
+export * from "./common/required";
+export * from "./common/requiredGroups";
+export * from "./common/property";
+export * from "./common/hidden";
+export * from "./common/title";
+export * from "./common/schema";
+export * from "./common/oneOf";
+export * from "./common/allOf";
+export * from "./common/anyOf";
+export * from "./common/jsonEntityFn";
+export * from "./common/optional";
+export * from "./common/writeOnly";
+export * from "./common/readOnly";
+export * from "./common/customKey";
+export * from "./common/nullable";
+export * from "./config/jsonEntityComponent";

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

@@ -0,0 +1,19 @@
+/**
+ * Add consumes metadata on the decorated element.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * class Model {
+ *    @Consumes("application/x-www-form-urlencoded")
+ *    id: string;
+ * }
+ * ```
+ *
+ * @param consumes
+ * @decorator
+ * @swagger
+ * @classDecorator
+ * @operation
+ */
+export declare function Consumes(...consumes: string[]): (...args: any[]) => any;

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

@@ -0,0 +1,20 @@
+/**
+ * Sets the Content-Type HTTP header to the MIME type as determined by mime.lookup() for the specified type.
+ * If type contains the “/” character, then it sets the `Content-Type` to type.
+ *
+ * ```typescript
+ *  @ContentType('.html');              // => 'text/html'
+ *  @ContentType('html');               // => 'text/html'
+ *  @ContentType('json');               // => 'application/json'
+ *  @ContentType('application/json');   // => 'application/json'
+ *  @ContentType('png');                // => image/png
+ *  private myMethod() {}
+ * ```
+ *
+ * @param type
+ * @decorator
+ * @operation
+ * @response
+ * @headers
+ */
+export declare function ContentType(type: string): import("./returns").ReturnsChainedDecorators;

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

@@ -0,0 +1,23 @@
+/**
+ * Add deprecated metadata on the decorated element.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ *
+ * @Deprecated()
+ * class MyCtrl {
+ *   @Deprecated()
+ *   @Get("/")
+ *   method(){
+ *   }
+ * }
+ * ```
+ *
+ * @param deprecated
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export declare function Deprecated(deprecated?: boolean): (...args: any[]) => any;

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

@@ -0,0 +1,49 @@
+import { JsonHeader, JsonHeaders } from "../../interfaces/JsonOpenSpec";
+/**
+ * Sets the response’s HTTP header field to value. To set multiple fields at once, pass an object as the parameter.
+ *
+ * ```typescript
+ * @Header('Content-Type', 'text/plain');
+ * private myMethod() {}
+ *
+ * @Status(204)
+ * @Header({
+ *   "Content-Type": "text/plain",
+ *   "Content-Length": 123,
+ *   "ETag": {
+ *     "value": "12345",
+ *     "description": "header description"
+ *   }
+ * })
+ * private myMethod() {}
+ * ```
+ *
+ * This example will produce the swagger responses object:
+ *
+ * ```json
+ * {
+ *   "responses": {
+ *     "204": {
+ *       "description": "Description",
+ *       "headers": {
+ *          "Content-Type": {
+ *             "type": "string"
+ *          },
+ *          "Content-Length": {
+ *             "type": "number"
+ *          },
+ *          "ETag": {
+ *             "type": "string",
+ *             "description": "header description"
+ *          }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @decorator
+ * @operation
+ * @response
+ */
+export declare function Header(headers: string | number | JsonHeaders, value?: string | number | JsonHeader): Function;

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

@@ -0,0 +1,64 @@
+import { Type } from "@tsed/core";
+import { JsonSchemaObject } from "../../domain";
+import { JsonParameterTypes } from "../../domain/JsonParameterTypes";
+export interface InChainedDecorators {
+    <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void;
+    (target: Object, propertyKey: string | symbol, parameterIndex: number): void;
+    (target: Function): void;
+    /**
+     * Type of this in parameter
+     * @param type
+     */
+    Type(type: Type<any>): this;
+    /**
+     *
+     * @param name
+     */
+    Name(name: string): this;
+    /**
+     *
+     * @param description
+     */
+    Description(description: string): this;
+    /**
+     *
+     * @param required
+     */
+    Required(required?: boolean): this;
+    /**
+     * Add pattern constraint. Only available for OPENAPI.
+     * @param pattern
+     */
+    Pattern(pattern: string | RegExp): this;
+    /**
+     * Add custom schema.
+     * @param schema
+     */
+    Schema(schema: Partial<JsonSchemaObject>): this;
+}
+/**
+ * Add a input parameter.
+ *
+ * ::: warning
+ * Don't use decorator with Ts.ED application to decorate parameters. Use @@BodyParams@@, @@PathParams@@, etc... instead.
+ * But you can use this decorator on Method, to add extra in parameters like Authorization header.
+ *
+ * ```typescript
+ * @Controller("/")
+ * class MyController {
+ *    @Get("/")
+ *    @In("header").Type(String).Name("Authorization").Required()
+ *    method() {
+ *    }
+ *  }
+ * ```
+ * :::
+ *
+ * @param inType
+ * @decorator
+ * @swagger
+ * @schema
+ * @input
+ * @operation
+ */
+export declare function In(inType: JsonParameterTypes | string): InChainedDecorators;

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

@@ -0,0 +1,22 @@
+import { JsonHeader } from "../../interfaces/JsonOpenSpec";
+/**
+ * Sets the response Location HTTP header to the specified path parameter.
+ *
+ * ```typescript
+ *  @Location('/foo/bar', {description: 'Location to the next step'})
+ *  @Location('http://example.com')
+ *  @Location('back')
+ *  private myMethod() {
+ *
+ *  }
+ * ```
+ *
+ * A path value of “back” has a special meaning, it refers to the URL specified in the `Referer` header of the request. If the `Referer` header was not specified, it refers to “/”.
+ *
+ * @param location
+ * @param meta
+ * @returns {Function}
+ * @decorator
+ * @operation
+ */
+export declare function Location(location: string, meta?: JsonHeader): import("./returns").ReturnsChainedDecorators;

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

@@ -0,0 +1,10 @@
+/**
+ * Set a swagger operationId explicitly.
+ *
+ * @param operationId
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export declare function OperationId(operationId: string): (...args: any[]) => any;

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

@@ -0,0 +1,21 @@
+import { OperationMethods } from "../../constants/httpMethods";
+/**
+ * Declare new Operation with his path and http method.
+ *
+ * ::: warning
+ * Don't use decorator with Ts.ED application.
+ *
+ * Use theses decorators instead:
+ *
+ * <ApiList query="status.includes('decorator') && status.includes('httpMethod')" />
+ *
+ * :::
+ *
+ * @param method
+ * @param path
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export declare function OperationPath(method: OperationMethods | string, path?: string | RegExp): (...args: any[]) => any;

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

@@ -0,0 +1,10 @@
+/**
+ * Apply Partial group strategy on the input model
+ *
+ * @decorator
+ * @validation
+ * @swagger
+ * @schema
+ * @input
+ */
+export declare function Partial(): ParameterDecorator;

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

@@ -0,0 +1,15 @@
+/**
+ * Set class path to expose all endpoints
+ *
+ * ::: warning
+ * Don't use this decorator to change the path if you develop your application with Ts.ED.
+ * :::
+ *
+ * @param path
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export declare function Path(path: string): (...args: any[]) => any;

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

@@ -0,0 +1,26 @@
+/**
+ * Add produces metadata on the decorated element.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * class Model {
+ *    @Produces("text/html")
+ *    id: string;
+ * }
+ * ```
+ *
+ * ::: warning
+ * For openspec v3 prefer `@Returns().ContentType()` usage (see @@Returns@@).
+ * :::
+ *
+ * @param produces
+ * @decorator
+ * @swagger
+ * @methodDecorator
+ * @classDecorator
+ * @operation
+ * @response
+ */
+export declare function Produces(...produces: string[]): (...args: any[]) => any;

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

@@ -0,0 +1,52 @@
+import { JsonHeader } from "../../interfaces/JsonOpenSpec";
+/**
+ * Redirects to the URL derived from the specified path, with specified status, a positive integer that corresponds to an HTTP status code . If not specified, status defaults to “302 “Found”.
+ *
+ * ```typescript
+ *  @Redirect('/foo/bar')
+ *  @Redirect(301, 'http://example.com').Type(Model)
+ *  private myMethod() {}
+ * ```
+ * Redirects can be a fully-qualified URL for redirecting to a different site:
+ *
+ * ```typescript
+ *  @Redirect('http://google.com');
+ *  private myMethod() {}
+ * ```
+ *
+ * Redirects can be relative to the root of the host name. For example, if the application is on http://example.com/admin/post/new, the following would redirect to the URL http://example.com/admin:
+ *
+ * ```typescript
+ *  @Redirect('/admin');
+ * ```
+ * Redirects can be relative to the current URL. For example, from http://example.com/blog/admin/ (notice the trailing slash), the following would redirect to the URL http://example.com/blog/admin/post/new.
+ *
+ * ```typescript
+ *  @Redirect('post/new');
+ * ```
+ *
+ * Redirecting to post/new from http://example.com/blog/admin (no trailing slash), will redirect to http://example.com/blog/post/new.
+ *
+ * If you found the above behavior confusing, think of path segments as directories (with trailing slashes) and files, it will start to make sense.
+ *
+ * Path-relative redirects are also possible. If you were on http://example.com/admin/post/new, the following would redirect to http//example.com/admin/post:
+ *
+ * ```typescript
+ *  @Redirect('..');
+ * ``
+ *
+ * A back redirection redirects the request back to the referer, defaulting to / when the referer is missing.
+ *
+ * ```typescript
+ *  @Redirect('back');
+ * ```
+ *
+ * @param url
+ * @param meta
+ * @decorator
+ * @operation
+ * @response
+ * @headers
+ */
+export declare function Redirect(url: string, meta?: JsonHeader): Function;
+export declare function Redirect(status: number, url: string, meta?: JsonHeader): Function;