@lakutata/core 1.0.59 → 3.0.0-beta.0

package/dist/esm/lib/dto/DTO.js

@@ -0,0 +1,458 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var DTO_1;
+import { DataValidator } from './DataValidator.js';
+import { defineObjectAsDTO, getCachedDTOSchema, getObjectIndexSignatureSchemaByConstructor, invalidateDTOSchemas, getObjectIndexSignatureSchemaByPrototype, getObjectSchemaByConstructor, getObjectSchemaByPrototype, setObjectPropertySchema, setObjectSchemaRefinement } from './ObjectSchemaValidation.js';
+import { InvalidValueException } from '../../exceptions/dto/InvalidValueException.js';
+import { withCause } from '../helpers/internal/WithCause.js';
+import { VLD, VLDMethods } from '../validation/VLD.js';
+import { isSymbol } from '@lakutata/utils/IsSymbol';
+import { As } from '@lakutata/utils/As';
+import { objectConstructor } from '@lakutata/utils/ObjectConstructor';
+import { toJsonSchema } from '../validation/JsonSchema.js';
+import { importObject } from '../validation/engine/json-schema/import.js';
+import { SchemaConversionException } from '../validation/exceptions/SchemaConversionException.js';
+/**
+ * Get DTO's object schema
+ * @param target
+ */
+function getObjectSchema(target) {
+    return getCachedDTOSchema(instanceSchemaCache, objectConstructor(target), () => {
+        const indexSignatureSchema = getObjectIndexSignatureSchemaByPrototype(target);
+        const objectSchema = getObjectSchemaByPrototype(target);
+        return indexSignatureSchema ? objectSchema.pattern(DTO.String(), indexSignatureSchema) : objectSchema;
+    });
+}
+/**
+ * Schemas validating DTO instances (without description), per DTO class
+ */
+const instanceSchemaCache = new WeakMap();
+/**
+ * Schemas returned by DTO.Schema(), per DTO class
+ */
+const classSchemaCache = new WeakMap();
+/**
+ * The schemas validating a single property, per DTO class (null: the whole object is validated)
+ */
+const propertySchemaCache = new WeakMap();
+/**
+ * The flags of an object schema which do not constrain its properties together
+ */
+const PROPERTY_INDEPENDENT_FLAGS = ['presence', 'description', 'label', 'unknown'];
+/**
+ * Whether the properties of an object schema are validated independently: no rule, dependency, rename, condition,
+ * value list or reference constrains them together
+ * @param objectSchema
+ */
+function arePropertiesIndependent(objectSchema) {
+    const terms = objectSchema.$_terms;
+    for (const term of ['dependencies', 'renames', 'externals', 'whens', 'alterations']) {
+        const value = terms[term];
+        if (value && (!Array.isArray(value) || value.length))
+            return false;
+    }
+    if (objectSchema._rules.length || objectSchema._valids || objectSchema._invalids)
+        return false;
+    for (const [flag, value] of Object.entries(objectSchema._flags)) {
+        if (!PROPERTY_INDEPENDENT_FLAGS.includes(flag) || (flag === 'unknown' && typeof value === 'object'))
+            return false;
+    }
+    const keys = (terms.keys || []);
+    //A property referring to other properties (or referred to) is validated with them
+    return keys.every(({ schema }) => !schema.$_rootReferences().length);
+}
+/**
+ * The schema validating a single property of a DTO, with the same label, path and preferences as the object schema
+ * (null: the property is validated with the whole object)
+ * @param instance
+ * @param propertyKey
+ */
+function getPropertySchema(instance, propertyKey) {
+    const schemas = getCachedDTOSchema(propertySchemaCache, objectConstructor(instance), () => new Map());
+    let schema = schemas.get(propertyKey);
+    if (schema !== undefined)
+        return schema;
+    schema = null;
+    const objectSchema = As(getObjectSchema(instance));
+    if (arePropertiesIndependent(objectSchema)) {
+        const child = (objectSchema.$_terms.keys || []).find(({ key }) => key === propertyKey);
+        if (child) {
+            const propertyObjectSchema = As(VLD.object({ [propertyKey]: child.schema }));
+            schema = As(objectSchema._preferences ? propertyObjectSchema.prefs(objectSchema._preferences) : propertyObjectSchema);
+        }
+    }
+    schemas.set(propertyKey, schema);
+    return schema;
+}
+/**
+ * Validate property value (only the property when the properties are validated independently)
+ * @param instance
+ * @param propertyKey
+ * @param value
+ */
+function validatePropertyValue(instance, propertyKey, value) {
+    if (typeof propertyKey === 'string') {
+        const propertySchema = getPropertySchema(instance, propertyKey);
+        if (propertySchema)
+            return DTO.validate({ [propertyKey]: value }, propertySchema, { noDefaults: true })[propertyKey];
+    }
+    return DTO.validate({ ...instance, [propertyKey]: value }, getObjectSchema(instance), { noDefaults: true })[propertyKey];
+}
+/**
+ * The array methods which change the array
+ */
+const ARRAY_MUTATORS = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'fill', 'copyWithin'];
+/**
+ * Restore the items of an array (its holes included)
+ * @param array
+ * @param snapshot
+ */
+function restoreArray(array, snapshot) {
+    array.length = 0;
+    for (let i = 0; i < snapshot.length; ++i) {
+        if (i in snapshot)
+            array[i] = snapshot[i];
+    }
+    array.length = snapshot.length;
+}
+/**
+ * Restore a property of an object after a rejected change: its previous value, or its absence (and the length of an
+ * array)
+ * @param target
+ * @param prop
+ * @param state
+ */
+function restoreProperty(target, prop, state) {
+    if (state.had) {
+        Reflect.set(target, prop, state.value);
+    }
+    else {
+        Reflect.deleteProperty(target, prop);
+    }
+    if (state.length !== undefined)
+        target.length = state.length;
+}
+/**
+ * The state of a property before a change
+ * @param target
+ * @param prop
+ */
+function propertyState(target, prop) {
+    return {
+        had: Object.prototype.hasOwnProperty.call(target, prop),
+        value: Reflect.get(target, prop),
+        length: Array.isArray(target) ? target.length : undefined
+    };
+}
+/**
+ * Return dynamic property proxy object
+ * @param target
+ * @param prop
+ * @param receiver
+ * @param validateFn
+ */
+function dynamicProxyProperty(target, prop, receiver, validateFn) {
+    const propertyValue = Reflect.get(target, prop, receiver);
+    if (!propertyValue)
+        return propertyValue;
+    if (typeof propertyValue !== 'object') {
+        if (typeof propertyValue !== 'function')
+            return propertyValue;
+        //A change made by an array method is validated once it is done (its steps may be invalid), and undone if invalid
+        if (Array.isArray(target) && typeof prop === 'string' && ARRAY_MUTATORS.includes(prop)) {
+            return (...args) => {
+                const snapshot = target.slice();
+                try {
+                    const result = propertyValue.apply(target, args);
+                    validateFn();
+                    return result;
+                }
+                catch (e) {
+                    restoreArray(target, snapshot);
+                    throw e;
+                }
+            };
+        }
+        return propertyValue.bind(target);
+    }
+    return new Proxy(propertyValue, {
+        set(target, p, value, receiver) {
+            const state = propertyState(target, p);
+            try {
+                const isSuccess = Reflect.set(target, p, value, receiver);
+                validateFn();
+                return isSuccess;
+            }
+            catch (e) {
+                restoreProperty(target, p, state);
+                throw e;
+            }
+        },
+        get(target, p, receiver) {
+            return dynamicProxyProperty(target, p, receiver, validateFn);
+        },
+        deleteProperty: (target, prop) => {
+            const state = propertyState(target, prop);
+            try {
+                const isSuccess = Reflect.deleteProperty(target, prop);
+                validateFn();
+                return isSuccess;
+            }
+            catch (e) {
+                restoreProperty(target, prop, state);
+                throw e;
+            }
+        }
+    });
+}
+const DTODescriptionSymbol = Symbol('DTO.DESCRIPTION');
+/**
+ * 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: ''}))
+ * ```
+ */
+let DTO = DTO_1 = 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 = {}) {
+        super();
+        //Create DTO proxy object
+        const DTOInstanceProxy = new Proxy(this, {
+            set: (target, prop, value, receiver) => {
+                if (!isSymbol(prop))
+                    value = validatePropertyValue(this, prop, value);
+                return Reflect.set(target, prop, value, receiver);
+            },
+            get: (target, p, receiver) => dynamicProxyProperty(target, p, receiver, () => {
+                //A nested change is validated with the property holding it
+                if (isSymbol(p)) {
+                    DTO_1.validate({ ...this }, getObjectSchema(this), { noDefaults: true });
+                }
+                else {
+                    validatePropertyValue(this, p, Reflect.get(target, p));
+                }
+            }),
+            deleteProperty: (target, prop) => {
+                if (!isSymbol(prop))
+                    validatePropertyValue(this, prop, void (0));
+                return Reflect.deleteProperty(target, prop);
+            }
+        });
+        try {
+            const validProps = DTO_1.validate(props, getObjectSchema(this));
+            Object.keys(validProps).forEach((propertyKey) => Reflect.set(this, propertyKey, validProps[propertyKey]));
+        }
+        catch (e) {
+            throw withCause(new InvalidValueException((As(e).message)), e);
+        }
+        return DTOInstanceProxy;
+    }
+    /**
+     * 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
+     */
+    static prepareValidation(schemaOrOptions, options) {
+        const schema = schemaOrOptions ? VLDMethods.isSchema(schemaOrOptions) ? As(schemaOrOptions) : this.Schema() : this.Schema();
+        const validateOptions = options ? options : schemaOrOptions ? VLDMethods.isSchema(schemaOrOptions) ? {} : As(schemaOrOptions) : {};
+        return {
+            schema: schema,
+            options: validateOptions
+        };
+    }
+    /**
+     * 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', options = {}) {
+        return toJsonSchema(this, { ...options, target: version });
+    }
+    /**
+     * 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.1', options = {}) {
+        return toJsonSchema(this, { ...options, target: version === '3.0' ? 'openapi-3.0' : 'openapi-3.1' });
+    }
+    /**
+     * 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(schema, options = {}) {
+        const imported = importObject(schema, options);
+        const BaseDTO = this;
+        const name = options.name || imported.title || `${BaseDTO.name}FromJsonSchema`;
+        //A named subclass
+        const GeneratedDTO = As({ [name]: class extends BaseDTO {
+            } }[name]);
+        for (const [propertyKey, propertySchema] of Object.entries(imported.keys))
+            setObjectPropertySchema(GeneratedDTO.prototype, propertyKey, As(propertySchema));
+        setObjectSchemaRefinement(GeneratedDTO, (objectSchema) => As(imported.refine(As(objectSchema))));
+        if (imported.description)
+            GeneratedDTO.description(imported.description);
+        return GeneratedDTO;
+    }
+    /**
+     * 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(document, options = {}) {
+        const version = document.openapi;
+        const dialect = options.dialect || (typeof version === 'string' && version.startsWith('3.0') ? 'openapi-3.0' : 'openapi-3.1');
+        const components = document.components?.schemas;
+        if (!components || typeof components !== 'object')
+            throw new SchemaConversionException('The OpenAPI document has no schemas');
+        const result = {};
+        for (const [name, component] of Object.entries(components)) {
+            //Only the schemas of objects are classes
+            if (!component || typeof component !== 'object')
+                continue;
+            const type = component.type;
+            if (type !== undefined && type !== 'object')
+                continue;
+            const pointer = `#/components/schemas/${name.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+            result[name] = this.fromJsonSchema({ $ref: pointer }, { ...options, dialect, document, name });
+        }
+        return result;
+    }
+    /**
+     * 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) {
+        Reflect.defineMetadata(DTODescriptionSymbol, desc, this);
+        invalidateDTOSchemas();
+        return this;
+    }
+    /**
+     * 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() {
+        return getCachedDTOSchema(classSchemaCache, this, () => {
+            const objectSchema = getObjectSchemaByConstructor(this);
+            const indexSignatureSchema = getObjectIndexSignatureSchemaByConstructor(this);
+            const description = Reflect.getOwnMetadata(DTODescriptionSymbol, this);
+            const finalSchema = indexSignatureSchema ? objectSchema.pattern(DTO_1.String(), indexSignatureSchema) : objectSchema;
+            return description === undefined ? finalSchema : finalSchema.description(description);
+        });
+    }
+    /**
+     * Get the class schema marked as required: `undefined` is rejected.
+     * @returns A new object schema.
+     */
+    static required() {
+        return this.Schema().required();
+    }
+    /**
+     * Get the class schema marked as optional: `undefined` is accepted (as by `Schema()`).
+     * @returns A new object schema.
+     */
+    static optional() {
+        return this.Schema().optional();
+    }
+    /**
+     * 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) {
+        return this.Schema().options(options);
+    }
+    static isValid(data, schemaOrOptions, validateOptions) {
+        const { schema, options } = this.prepareValidation(schemaOrOptions, validateOptions);
+        return VLDMethods.isValid(data, schema, options);
+    }
+    static async isValidAsync(data, schemaOrOptions, validateOptions) {
+        const { schema, options } = this.prepareValidation(schemaOrOptions, validateOptions);
+        return await VLDMethods.isValidAsync(data, schema, options);
+    }
+    static validate(data, schemaOrOptions, validateOptions) {
+        const { schema, options } = this.prepareValidation(schemaOrOptions, validateOptions);
+        return VLDMethods.validate(data, schema, options);
+    }
+    static async validateAsync(data, schemaOrOptions, validateOptions) {
+        const { schema, options } = this.prepareValidation(schemaOrOptions, validateOptions);
+        return await VLDMethods.validateAsync(data, schema, options);
+    }
+};
+DTO = DTO_1 = __decorate([
+    ((target) => defineObjectAsDTO(target)),
+    __metadata("design:paramtypes", [Object])
+], DTO);
+export { DTO };