@lakutata/core 1.0.60 → 3.0.0-beta.0

package/dist/cjs/lib/dto/DTO.d.ts

@@ -0,0 +1,278 @@
+import { DataValidator } from './DataValidator.js';
+import { ValidationOptions } from '../validation/interfaces/ValidationOptions.js';
+import { Schema } from '../validation/types/Schema.js';
+import { ObjectSchema } from '../validation/interfaces/ObjectSchema.js';
+import { type FromJsonSchemaOptions, type ToJsonSchemaOptions } from '../validation/JsonSchema.js';
+import { JSONSchema } from '../../types/JSONSchema.js';
+/**
+ * The base class of the data transfer objects: a class whose properties are declared with schemas (`@Expect`), and
+ * which validates its data when it is constructed and each time it is changed. Its static methods validate any value
+ * (`DTO.validate()`), build schemas (`DTO.String()`, `DTO.Object()`…), and convert the class schema to or from JSON
+ * Schema. A DTO class is also a schema wherever one is expected: `@Accept`, `@Return`, the input of the controller
+ * actions. The schemas built by `DTO` are strict: a value of the wrong type is rejected, not converted (the string `'5'`
+ * is not the number 5).
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Expect} from 'lakutata/decorator/dto'
+ *
+ * class AddressDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public city!: string
+ *
+ *     @Expect(DTO.String().pattern(/^[0-9]{5}$/).optional())
+ *     public zip?: string
+ * }
+ *
+ * class CustomerDTO extends DTO {
+ *     @Expect(DTO.String().min(1).required())
+ *     public name!: string
+ *
+ *     @Expect(AddressDTO.required())
+ *     public address!: AddressDTO
+ * }
+ *
+ * //Validated when constructed, the unknown key "note" removed
+ * const customer: CustomerDTO = new CustomerDTO({name: 'Ada', address: {city: 'London'}, note: 'vip'})
+ * //Validated without an instance: the validated value, or an InvalidValueException
+ * const data: CustomerDTO = CustomerDTO.validate({name: 'Ada', address: {city: 'London'}})
+ * //Checked without exception
+ * console.log(customer.name, data.address.city, CustomerDTO.isValid({name: ''}))
+ * ```
+ */
+export declare class DTO extends DataValidator {
+    /**
+     * Create a DTO from its data, validated against the class schema: the defaults applied, the keys without schema
+     * removed (unless the class has an `@IndexSignature`). The instance then validates each change of a property, or
+     * of a value nested in it (an array, an object): an invalid change throws an `InvalidValueException` and is
+     * undone.
+     * @param props The data of the DTO. Default: no data (`{}`).
+     * @throws {InvalidValueException} When the data does not match the class schema.
+     */
+    constructor(props?: Record<string, any>);
+    [prop: string | symbol]: any;
+    /**
+     * Resolve the arguments of the validation methods: the schema given, else the class schema (`this.Schema()`), and
+     * the validation options.
+     * @param schemaOrOptions The schema to validate against, or the validation options when no schema is given.
+     * @param options The validation options, when a schema is given. Default: no option (`{}`).
+     * @returns The schema and the options to validate with.
+     * @protected
+     */
+    protected static prepareValidation(schemaOrOptions?: Schema | ValidationOptions, options?: ValidationOptions): {
+        schema: Schema;
+        options: ValidationOptions;
+    };
+    /**
+     * Convert the class schema to a JSON Schema, for an API document or another validator. What JSON Schema cannot
+     * express (custom rules, references to other values) is dropped, so the JSON Schema may accept more values, never
+     * less.
+     * @param version The JSON Schema version to write. Default `'draft-2020-12'`.
+     * @param options The validation options the schema is used with, whether `$schema` is written, and the object
+     * receiving the shared schemas. Default: no option (`{}`).
+     * @returns A new JSON Schema.
+     * @throws {SchemaConversionException} When the version is unknown.
+     */
+    static toJsonSchema(version?: 'draft-2020-12' | 'draft-2019-09' | 'draft-07' | 'draft-04', options?: Omit<ToJsonSchemaOptions, 'target'>): JSONSchema;
+    /**
+     * Convert the class schema to an OpenAPI schema object, for the `components.schemas` of an OpenAPI document.
+     * @param version The OpenAPI version: `'3.0'` or `'3.1'`. Default `'3.1'`.
+     * @param options The validation options the schema is used with, and the object receiving the shared schemas.
+     * Default: no option (`{}`).
+     * @returns A new OpenAPI schema object.
+     */
+    static toOpenAPIJsonSchema(version?: '3.0' | '3.1', options?: Omit<ToJsonSchemaOptions, 'target' | 'dialect'>): JSONSchema;
+    /**
+     * Create a DTO class (a subclass of the current DTO class) from an object JSON Schema (or an OpenAPI schema object),
+     * validating like JSON Schema: its properties become the properties of the DTO, its other keywords (unknown keys,
+     * pattern properties, key counts, dependencies, subschemas) constrain the whole object.
+     * @param schema The JSON Schema of an object (or an OpenAPI schema object), or a reference (`$ref`) to one.
+     * @param options The version of the JSON Schema, where its references are resolved, whether the values are
+     * converted, and the name of the class. Default `name`: the title of the JSON Schema, else the current class
+     * name followed by `FromJsonSchema`.
+     * @returns The new DTO class.
+     * @throws {SchemaConversionException} When the JSON Schema does not describe objects, a reference cannot be
+     * resolved, or a pattern is not a valid regular expression.
+     */
+    static fromJsonSchema<T extends typeof DTO>(this: T, schema: JSONSchema, options?: FromJsonSchemaOptions & {
+        name?: string;
+    }): T;
+    /**
+     * Create the DTO classes of the object schemas of an OpenAPI document (its components.schemas), by name; the
+     * references between the schemas are resolved in the document. The schemas which do not describe objects are
+     * skipped.
+     * @param document The OpenAPI 3.0 or 3.1 document.
+     * @param options How the JSON Schemas are read. Default `dialect`: the version of the document's `openapi` field.
+     * @returns The DTO classes, by the names of their schemas.
+     * @throws {SchemaConversionException} When the document has no `components.schemas`, or a schema cannot be
+     * converted.
+     */
+    static fromOpenAPI<T extends typeof DTO>(this: T, document: Record<string, unknown>, options?: Omit<FromJsonSchemaOptions, 'document'>): Record<string, T>;
+    /**
+     * Set the description of the class schema, written into its JSON Schema and its descriptions. The description is
+     * not inherited by the subclasses.
+     * @param desc The description.
+     * @returns The class itself, for chaining.
+     */
+    static description(desc: string): typeof DTO;
+    /**
+     * Get the class schema: an object schema of the properties declared with `@Expect` (the parents' included), with
+     * the `@IndexSignature` and the description of the class. The schema is optional (it accepts `undefined`): use
+     * `required()` for a required one.
+     * @returns The object schema; the same instance until a schema declaration changes.
+     */
+    static Schema(): ObjectSchema;
+    /**
+     * Get the class schema marked as required: `undefined` is rejected.
+     * @returns A new object schema.
+     */
+    static required(): ObjectSchema;
+    /**
+     * Get the class schema marked as optional: `undefined` is accepted (as by `Schema()`).
+     * @returns A new object schema.
+     */
+    static optional(): ObjectSchema;
+    /**
+     * Get the class schema with its own validation options, which override the options of the validation for the
+     * object and its nested values.
+     * @param options The validation options.
+     * @returns A new object schema.
+     */
+    static options(options: ValidationOptions): ObjectSchema;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing.
+     * @param data The value to check.
+     * @returns `true` when the value matches the schema, else `false`.
+     */
+    static isValid<T = any>(data: T): boolean;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing.
+     * @param data The value to check.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns `true` when the value matches the schema, else `false`.
+     */
+    static isValid<T = any>(data: T, options: ValidationOptions): boolean;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing.
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @returns `true` when the value matches the schema, else `false`.
+     */
+    static isValid<T = any>(data: T, schema: Schema): boolean;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing.
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns `true` when the value matches the schema, else `false`.
+     */
+    static isValid<T = any>(data: T, schema: Schema, options: ValidationOptions): boolean;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously,
+     * running the external rules of the schema.
+     * @param data The value to check.
+     * @returns A promise of `true` when the value matches the schema, else `false`.
+     */
+    static isValidAsync<T = any>(data: T): Promise<boolean>;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously,
+     * running the external rules of the schema.
+     * @param data The value to check.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns A promise of `true` when the value matches the schema, else `false`.
+     */
+    static isValidAsync<T = any>(data: T, options: ValidationOptions): Promise<boolean>;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously,
+     * running the external rules of the schema.
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @returns A promise of `true` when the value matches the schema, else `false`.
+     */
+    static isValidAsync<T = any>(data: T, schema: Schema): Promise<boolean>;
+    /**
+     * Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously,
+     * running the external rules of the schema.
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns A promise of `true` when the value matches the schema, else `false`.
+     */
+    static isValidAsync<T = any>(data: T, schema: Schema, options: ValidationOptions): Promise<boolean>;
+    /**
+     * Validate a value against a schema (the class schema when none is given).
+     * @param data The value to check.
+     * @returns The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
+     * @throws {InvalidValueException} When the value does not match the schema (its cause holds the details).
+     */
+    static validate<T = any>(data: T): T;
+    /**
+     * Validate a value against a schema (the class schema when none is given).
+     * @param data The value to check.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
+     * @throws {InvalidValueException} When the value does not match the schema (its cause holds the details).
+     */
+    static validate<T = any>(data: T, options: ValidationOptions): T;
+    /**
+     * Validate a value against a schema (the class schema when none is given).
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @returns The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
+     * @throws {InvalidValueException} When the value does not match the schema (its cause holds the details).
+     */
+    static validate<T = any>(data: T, schema: Schema): T;
+    /**
+     * Validate a value against a schema (the class schema when none is given).
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
+     * @throws {InvalidValueException} When the value does not match the schema (its cause holds the details).
+     */
+    static validate<T = any>(data: T, schema: Schema, options: ValidationOptions): T;
+    /**
+     * Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of
+     * the schema (`.external()`) run, which the synchronous validation cannot run.
+     * @param data The value to check.
+     * @returns A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO
+     * instance).
+     * @throws {InvalidValueException} When the value does not match the schema (the promise rejects; its cause holds
+     * the details).
+     */
+    static validateAsync<T = any>(data: T): Promise<T>;
+    /**
+     * Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of
+     * the schema (`.external()`) run, which the synchronous validation cannot run.
+     * @param data The value to check.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO
+     * instance).
+     * @throws {InvalidValueException} When the value does not match the schema (the promise rejects; its cause holds
+     * the details).
+     */
+    static validateAsync<T = any>(data: T, options: ValidationOptions): Promise<T>;
+    /**
+     * Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of
+     * the schema (`.external()`) run, which the synchronous validation cannot run.
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @returns A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO
+     * instance).
+     * @throws {InvalidValueException} When the value does not match the schema (the promise rejects; its cause holds
+     * the details).
+     */
+    static validateAsync<T = any>(data: T, schema: Schema): Promise<T>;
+    /**
+     * Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of
+     * the schema (`.external()`) run, which the synchronous validation cannot run.
+     * @param data The value to check.
+     * @param schema The schema to check against, instead of the class schema.
+     * @param options The validation options, merged with the defaults (unknown keys removed, the first error only).
+     * @returns A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO
+     * instance).
+     * @throws {InvalidValueException} When the value does not match the schema (the promise rejects; its cause holds
+     * the details).
+     */
+    static validateAsync<T = any>(data: T, schema: Schema, options: ValidationOptions): Promise<T>;
+}