@rtpaulino/entity 0.13.0 → 0.14.1

package/dist/index.d.ts

@@ -3,4 +3,8 @@ export * from './lib/entity.js';
 export * from './lib/entity-utils.js';
 export * from './lib/types.js';
 export * from './lib/property.js';
+export * from './lib/validation-error.js';
+export * from './lib/problem.js';
+export * from './lib/validation-utils.js';
+export * from './lib/primitive-deserializers.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC"}

package/dist/index.js

@@ -3,5 +3,9 @@ export * from './lib/entity.js';
 export * from './lib/entity-utils.js';
 export * from './lib/types.js';
 export * from './lib/property.js';
+export * from './lib/validation-error.js';
+export * from './lib/problem.js';
+export * from './lib/validation-utils.js';
+export * from './lib/primitive-deserializers.js';
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import 'reflect-metadata';\n\nexport * from './lib/entity.js';\nexport * from './lib/entity-utils.js';\nexport * from './lib/types.js';\nexport * from './lib/property.js';\n"],"names":[],"mappings":"AAAA,OAAO,mBAAmB;AAE1B,cAAc,kBAAkB;AAChC,cAAc,wBAAwB;AACtC,cAAc,iBAAiB;AAC/B,cAAc,oBAAoB"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import 'reflect-metadata';\n\nexport * from './lib/entity.js';\nexport * from './lib/entity-utils.js';\nexport * from './lib/types.js';\nexport * from './lib/property.js';\nexport * from './lib/validation-error.js';\nexport * from './lib/problem.js';\nexport * from './lib/validation-utils.js';\nexport * from './lib/primitive-deserializers.js';\n"],"names":[],"mappings":"AAAA,OAAO,mBAAmB;AAE1B,cAAc,kBAAkB;AAChC,cAAc,wBAAwB;AACtC,cAAc,iBAAiB;AAC/B,cAAc,oBAAoB;AAClC,cAAc,4BAA4B;AAC1C,cAAc,mBAAmB;AACjC,cAAc,4BAA4B;AAC1C,cAAc,mCAAmC"}

package/dist/lib/entity-utils.d.ts

@@ -1,4 +1,5 @@
 import { PropertyOptions } from './types.js';
+import { Problem } from './problem.js';
 export declare class EntityUtils {
     /**
      * Checks if a given object is an instance of a class decorated with @Entity()
@@ -92,7 +93,8 @@ export declare class EntityUtils {
      *
      * @param entityClass - The entity class constructor. Must accept a data object parameter.
      * @param plainObject - The plain object to deserialize
-     * @returns A new instance of the entity with deserialized values
+     * @param options - Parse options (strict mode)
+     * @returns Promise resolving to a new instance of the entity with deserialized values
      *
      * @remarks
      * Deserialization rules:
@@ -105,6 +107,14 @@ export declare class EntityUtils {
      * - Type conversion is strict (no coercion)
      * - Entity constructors must accept a required data parameter
      *
+     * Validation behavior:
+     * - If strict: true - both HARD and SOFT problems throw ValidationError
+     * - If strict: false (default) - HARD problems throw ValidationError, SOFT problems stored
+     * - Property validators run first, then entity validators
+     * - Validators can be synchronous or asynchronous
+     * - Problems are accessible via EntityUtils.problems()
+     * - Raw input data is accessible via EntityUtils.getRawInput()
+     *
      * @example
      * ```typescript
      * @Entity()
@@ -118,10 +128,13 @@ export declare class EntityUtils {
      * }
      *
      * const json = { name: 'John', age: 30 };
-     * const user = EntityUtils.parse(User, json);
+     * const user = await EntityUtils.parse(User, json);
+     * const userStrict = await EntityUtils.parse(User, json, { strict: true });
      * ```
      */
-    static parse<T extends object>(entityClass: new (data: any) => T, plainObject: Record<string, unknown>): T;
+    static parse<T extends object>(entityClass: new (data: any) => T, plainObject: unknown, options?: {
+        strict?: boolean;
+    }): Promise<T>;
     /**
      * Deserializes a single value according to the type metadata
      * @private
@@ -129,8 +142,81 @@ export declare class EntityUtils {
     private static deserializeValue;
     /**
      * Deserializes a single non-array value
+     * Reports validation errors with empty property (caller will prepend context)
      * @private
      */
     private static deserializeSingleValue;
+    /**
+     * Validates a property value by running validators and nested entity validation.
+     * Prepends the property path to all returned problems.
+     * @private
+     */
+    private static validatePropertyValue;
+    /**
+     * Runs property validators for a given property value
+     * @private
+     */
+    private static runPropertyValidators;
+    /**
+     * Validates an entity instance by running all property and entity validators
+     *
+     * @param instance - The entity instance to validate
+     * @returns Promise resolving to array of Problems found during validation (empty if valid)
+     *
+     * @remarks
+     * - Property validators run first, then entity validators
+     * - Each validator can be synchronous or asynchronous
+     * - Empty array means no problems found
+     *
+     * @example
+     * ```typescript
+     * const user = new User({ name: '', age: -5 });
+     * const problems = await EntityUtils.validate(user);
+     * console.log(problems); // [Problem, Problem, ...]
+     * ```
+     */
+    static validate<T extends object>(instance: T): Promise<Problem[]>;
+    /**
+     * Gets the validation problems for an entity instance
+     *
+     * @param instance - The entity instance
+     * @returns Array of Problems (empty if no problems or instance not parsed)
+     *
+     * @remarks
+     * - Only returns problems from the last parse() call
+     * - Returns empty array if instance was not created via parse()
+     * - Returns empty array if parse() was called with strict: true
+     *
+     * @example
+     * ```typescript
+     * const user = EntityUtils.parse(User, data);
+     * const problems = EntityUtils.problems(user);
+     * console.log(problems); // [Problem, ...]
+     * ```
+     */
+    static problems<T extends object>(instance: T): Problem[];
+    /**
+     * Gets the raw input data that was used to create an entity instance
+     *
+     * @param instance - The entity instance
+     * @returns The raw input object, or undefined if not available
+     *
+     * @remarks
+     * - Only available for instances created via parse()
+     * - Returns a reference to the original input data (not a copy)
+     *
+     * @example
+     * ```typescript
+     * const user = EntityUtils.parse(User, { name: 'John', age: 30 });
+     * const rawInput = EntityUtils.getRawInput(user);
+     * console.log(rawInput); // { name: 'John', age: 30 }
+     * ```
+     */
+    static getRawInput<T extends object>(instance: T): Record<string, unknown> | undefined;
+    /**
+     * Gets all entity validator method names for an entity
+     * @private
+     */
+    private static getEntityValidators;
 }
 //# sourceMappingURL=entity-utils.d.ts.map

package/dist/lib/entity-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-utils.d.ts","sourceRoot":"","sources":["../../src/lib/entity-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM;IAmB5C,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAQhD,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAoChD,MAAM,CAAC,kBAAkB,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,eAAe,GAAG,SAAS;IA8B9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO;IA2B9C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,EAC1B,SAAS,EAAE,CAAC,EACZ,SAAS,EAAE,CAAC,GACX;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,EAAE;IAoC/D,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAaxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmBnE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAsD7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC3B,WAAW,EAAE,KAAK,IAAI,EAAE,GAAG,KAAK,CAAC,EACjC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,CAAC;IA6CJ;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IA4C/B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;CAoFtC"}
+{"version":3,"file":"entity-utils.d.ts","sourceRoot":"","sources":["../../src/lib/entity-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAuBvC,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM;IAmB5C,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAQhD,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAoChD,MAAM,CAAC,kBAAkB,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,eAAe,GAAG,SAAS;IA8B9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO;IA2B9C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,EAC1B,SAAS,EAAE,CAAC,EACZ,SAAS,EAAE,CAAC,GACX;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,EAAE;IAoC/D,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAaxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmBnE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAsD7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;WACU,KAAK,CAAC,CAAC,SAAS,MAAM,EACjC,WAAW,EAAE,KAAK,IAAI,EAAE,GAAG,KAAK,CAAC,EACjC,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC7B,OAAO,CAAC,CAAC,CAAC;IA8Gb;;;OAGG;mBACkB,gBAAgB;IAiErC;;;;OAIG;mBACkB,sBAAsB;IA0B3C;;;;OAIG;mBACkB,qBAAqB;IAkC1C;;;OAGG;mBACkB,qBAAqB;IAoD1C;;;;;;;;;;;;;;;;;OAiBG;WACU,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAkCxE;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,EAAE;IAIzD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,WAAW,CAAC,CAAC,SAAS,MAAM,EACjC,QAAQ,EAAE,CAAC,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAItC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;CA6BnC"}

package/dist/lib/entity-utils.js

@@ -1,5 +1,16 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */ import { ENTITY_METADATA_KEY, PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */ import { ENTITY_METADATA_KEY, ENTITY_VALIDATOR_METADATA_KEY, PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
 import { isEqualWith } from 'lodash-es';
+import { ValidationError } from './validation-error.js';
+import { Problem } from './problem.js';
+import { prependPropertyPath, prependArrayIndex, createValidationError, combinePropertyPaths } from './validation-utils.js';
+import { isPrimitiveConstructor, deserializePrimitive } from './primitive-deserializers.js';
+import { ok } from 'assert';
+/**
+ * WeakMap to store validation problems for entity instances
+ */ const problemsStorage = new WeakMap();
+/**
+ * WeakMap to store raw input data for entity instances
+ */ const rawInputStorage = new WeakMap();
 export class EntityUtils {
     /**
    * Checks if a given object is an instance of a class decorated with @Entity()
@@ -250,7 +261,8 @@ export class EntityUtils {
    *
    * @param entityClass - The entity class constructor. Must accept a data object parameter.
    * @param plainObject - The plain object to deserialize
-   * @returns A new instance of the entity with deserialized values
+   * @param options - Parse options (strict mode)
+   * @returns Promise resolving to a new instance of the entity with deserialized values
    *
    * @remarks
    * Deserialization rules:
@@ -263,6 +275,14 @@ export class EntityUtils {
    * - Type conversion is strict (no coercion)
    * - Entity constructors must accept a required data parameter
    *
+   * Validation behavior:
+   * - If strict: true - both HARD and SOFT problems throw ValidationError
+   * - If strict: false (default) - HARD problems throw ValidationError, SOFT problems stored
+   * - Property validators run first, then entity validators
+   * - Validators can be synchronous or asynchronous
+   * - Problems are accessible via EntityUtils.problems()
+   * - Raw input data is accessible via EntityUtils.getRawInput()
+   *
    * @example
    * ```typescript
    * @Entity()
@@ -276,125 +296,324 @@ export class EntityUtils {
    * }
    *
    * const json = { name: 'John', age: 30 };
-   * const user = EntityUtils.parse(User, json);
+   * const user = await EntityUtils.parse(User, json);
+   * const userStrict = await EntityUtils.parse(User, json, { strict: true });
    * ```
-   */ static parse(entityClass, plainObject) {
+   */ static async parse(entityClass, plainObject, options) {
+        if (plainObject == null) {
+            throw createValidationError(`Expects an object but received ${typeof plainObject}`);
+        }
+        if (Array.isArray(plainObject)) {
+            throw createValidationError(`Expects an object but received array`);
+        }
+        if (typeof plainObject !== 'object') {
+            throw createValidationError(`Expects an object but received ${typeof plainObject}`);
+        }
+        const strict = options?.strict ?? false;
         const keys = this.getPropertyKeys(entityClass.prototype);
         const data = {};
+        const hardProblems = [];
         for (const key of keys){
-            const options = this.getPropertyOptions(entityClass.prototype, key);
-            if (!options) {
-                throw new Error(`Property '${key}' has no metadata. This should not happen if @Property() was used correctly.`);
+            const propertyOptions = this.getPropertyOptions(entityClass.prototype, key);
+            if (!propertyOptions) {
+                hardProblems.push(new Problem({
+                    property: key,
+                    message: `Property has no metadata. This should not happen if @Property() was used correctly.`
+                }));
+                continue;
             }
-            if (options.passthrough === true) {
-                const value = plainObject[key];
+            const value = plainObject[key];
+            if (propertyOptions.passthrough === true) {
                 data[key] = value;
                 continue;
             }
-            const value = plainObject[key];
-            const isOptional = options.optional === true;
+            const isOptional = propertyOptions.optional === true;
             if (!(key in plainObject)) {
                 if (!isOptional) {
-                    throw new Error(`Property '${key}' is required but missing from input`);
+                    hardProblems.push(new Problem({
+                        property: key,
+                        message: 'Required property is missing from input'
+                    }));
                 }
                 continue;
             }
             if (value === null || value === undefined) {
                 if (!isOptional) {
-                    throw new Error(`Property '${key}' cannot be null or undefined`);
+                    hardProblems.push(new Problem({
+                        property: key,
+                        message: 'Cannot be null or undefined'
+                    }));
                 }
                 data[key] = value;
                 continue;
             }
-            data[key] = this.deserializeValue(value, options, key);
+            try {
+                data[key] = await this.deserializeValue(value, propertyOptions);
+            } catch (error) {
+                if (error instanceof ValidationError) {
+                    const problems = prependPropertyPath(key, error);
+                    hardProblems.push(...problems);
+                } else if (error instanceof Error) {
+                    hardProblems.push(new Problem({
+                        property: key,
+                        message: error.message
+                    }));
+                } else {
+                    throw error;
+                }
+            }
+        }
+        if (hardProblems.length > 0) {
+            throw new ValidationError(hardProblems);
         }
-        return new entityClass(data);
+        const instance = new entityClass(data);
+        rawInputStorage.set(instance, plainObject);
+        const problems = await this.validate(instance);
+        if (problems.length > 0) {
+            if (strict) {
+                throw new ValidationError(problems);
+            } else {
+                problemsStorage.set(instance, problems);
+            }
+        }
+        return instance;
     }
     /**
    * Deserializes a single value according to the type metadata
    * @private
-   */ static deserializeValue(value, options, propertyKey) {
+   */ static async deserializeValue(value, options) {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         const typeConstructor = options.type();
         const isArray = options.array === true;
         const isSparse = options.sparse === true;
         if (isArray) {
             if (!Array.isArray(value)) {
-                throw new Error(`Property '${propertyKey}' expects an array but received ${typeof value}`);
+                throw createValidationError(`Expects an array but received ${typeof value}`);
             }
-            return value.map((item, index)=>{
+            const arrayProblems = [];
+            const result = [];
+            for(let index = 0; index < value.length; index++){
+                const item = value[index];
                 if (item === null || item === undefined) {
                     if (!isSparse) {
-                        throw new Error(`Property '${propertyKey}[${index}]' cannot be null or undefined. Use sparse: true to allow null/undefined elements in arrays.`);
+                        arrayProblems.push(new Problem({
+                            property: `[${index}]`,
+                            message: 'Cannot be null or undefined.'
+                        }));
+                    }
+                    result.push(item);
+                } else {
+                    try {
+                        if (options.deserialize) {
+                            result.push(options.deserialize(item));
+                        } else {
+                            result.push(await this.deserializeSingleValue(item, typeConstructor));
+                        }
+                    } catch (error) {
+                        if (error instanceof ValidationError) {
+                            const problems = prependArrayIndex(index, error);
+                            arrayProblems.push(...problems);
+                        } else {
+                            throw error;
+                        }
                     }
-                    return item;
-                }
-                if (options.deserialize) {
-                    return options.deserialize(item);
                 }
-                return this.deserializeSingleValue(item, typeConstructor, `${propertyKey}[${index}]`);
-            });
+            }
+            if (arrayProblems.length > 0) {
+                throw new ValidationError(arrayProblems);
+            }
+            return result;
         }
         if (options.deserialize) {
             return options.deserialize(value);
         }
-        return this.deserializeSingleValue(value, typeConstructor, propertyKey);
+        return await this.deserializeSingleValue(value, typeConstructor);
     }
     /**
    * Deserializes a single non-array value
+   * Reports validation errors with empty property (caller will prepend context)
    * @private
-   */ static deserializeSingleValue(value, typeConstructor, propertyKey) {
-        if (typeConstructor === String) {
-            if (typeof value !== 'string') {
-                throw new Error(`Property '${propertyKey}' expects a string but received ${typeof value}`);
-            }
-            return value;
+   */ static async deserializeSingleValue(value, typeConstructor) {
+        if (isPrimitiveConstructor(typeConstructor)) {
+            return deserializePrimitive(value, typeConstructor);
         }
-        if (typeConstructor === Number) {
-            if (typeof value !== 'number') {
-                throw new Error(`Property '${propertyKey}' expects a number but received ${typeof value}`);
+        if (this.isEntity(typeConstructor)) {
+            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                throw createValidationError(`Expects an object but received ${typeof value}`);
             }
-            return value;
+            return await this.parse(typeConstructor, value);
         }
-        if (typeConstructor === Boolean) {
-            if (typeof value !== 'boolean') {
-                throw new Error(`Property '${propertyKey}' expects a boolean but received ${typeof value}`);
+        throw createValidationError(`Has unknown type constructor. Supported types are: String, Number, Boolean, Date, BigInt, and @Entity() classes. Use passthrough: true to explicitly allow unknown types.`);
+    }
+    /**
+   * Validates a property value by running validators and nested entity validation.
+   * Prepends the property path to all returned problems.
+   * @private
+   */ static async validatePropertyValue(propertyPath, value, validators) {
+        const problems = [];
+        if (validators) {
+            for (const validator of validators){
+                const validatorProblems = await validator({
+                    value
+                });
+                // Prepend propertyPath to all problems
+                for (const problem of validatorProblems){
+                    problems.push(new Problem({
+                        property: combinePropertyPaths(propertyPath, problem.property),
+                        message: problem.message
+                    }));
+                }
             }
-            return value;
         }
-        if (typeConstructor === BigInt) {
-            if (typeof value === 'bigint') {
-                return value;
+        if (EntityUtils.isEntity(value)) {
+            const nestedProblems = await EntityUtils.validate(value);
+            const prependedProblems = prependPropertyPath(propertyPath, new ValidationError(nestedProblems));
+            problems.push(...prependedProblems);
+        }
+        return problems;
+    }
+    /**
+   * Runs property validators for a given property value
+   * @private
+   */ static async runPropertyValidators(key, value, options) {
+        const problems = [];
+        const isArray = options?.array === true;
+        const isPassthrough = options?.passthrough === true;
+        if (isPassthrough || !isArray) {
+            const valueProblems = await this.validatePropertyValue(key, value, options.validators);
+            problems.push(...valueProblems);
+        } else {
+            ok(Array.isArray(value), 'Value must be an array for array property');
+            const arrayValidators = options.arrayValidators || [];
+            for (const validator of arrayValidators){
+                const validatorProblems = await validator({
+                    value
+                });
+                for (const problem of validatorProblems){
+                    problems.push(new Problem({
+                        property: combinePropertyPaths(key, problem.property),
+                        message: problem.message
+                    }));
+                }
             }
-            if (typeof value === 'string') {
-                try {
-                    return BigInt(value);
-                } catch  {
-                    throw new Error(`Property '${propertyKey}' cannot parse '${value}' as BigInt`);
+            const validators = options.validators || [];
+            if (validators.length > 0) {
+                for(let i = 0; i < value.length; i++){
+                    const element = value[i];
+                    if (element !== null && element !== undefined) {
+                        const elementPath = `${key}[${i}]`;
+                        const elementProblems = await this.validatePropertyValue(elementPath, element, validators);
+                        problems.push(...elementProblems);
+                    }
                 }
             }
-            throw new Error(`Property '${propertyKey}' expects a bigint or string but received ${typeof value}`);
         }
-        if (typeConstructor === Date) {
-            if (value instanceof Date) {
-                return value;
-            }
-            if (typeof value === 'string') {
-                const date = new Date(value);
-                if (isNaN(date.getTime())) {
-                    throw new Error(`Property '${propertyKey}' cannot parse '${value}' as Date`);
+        return problems;
+    }
+    /**
+   * Validates an entity instance by running all property and entity validators
+   *
+   * @param instance - The entity instance to validate
+   * @returns Promise resolving to array of Problems found during validation (empty if valid)
+   *
+   * @remarks
+   * - Property validators run first, then entity validators
+   * - Each validator can be synchronous or asynchronous
+   * - Empty array means no problems found
+   *
+   * @example
+   * ```typescript
+   * const user = new User({ name: '', age: -5 });
+   * const problems = await EntityUtils.validate(user);
+   * console.log(problems); // [Problem, Problem, ...]
+   * ```
+   */ static async validate(instance) {
+        if (!this.isEntity(instance)) {
+            throw new Error('Cannot validate non-entity instance');
+        }
+        const problems = [];
+        const keys = this.getPropertyKeys(instance);
+        for (const key of keys){
+            const options = this.getPropertyOptions(instance, key);
+            if (options) {
+                const value = instance[key];
+                if (value != null) {
+                    const validationProblems = await this.runPropertyValidators(key, value, options);
+                    problems.push(...validationProblems);
                 }
-                return date;
             }
-            throw new Error(`Property '${propertyKey}' expects a Date or ISO string but received ${typeof value}`);
         }
-        if (this.isEntity(typeConstructor)) {
-            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-                throw new Error(`Property '${propertyKey}' expects an object but received ${typeof value}`);
+        const entityValidators = this.getEntityValidators(instance);
+        for (const validatorMethod of entityValidators){
+            const validatorProblems = await instance[validatorMethod]();
+            if (Array.isArray(validatorProblems)) {
+                problems.push(...validatorProblems);
+            }
+        }
+        return problems;
+    }
+    /**
+   * Gets the validation problems for an entity instance
+   *
+   * @param instance - The entity instance
+   * @returns Array of Problems (empty if no problems or instance not parsed)
+   *
+   * @remarks
+   * - Only returns problems from the last parse() call
+   * - Returns empty array if instance was not created via parse()
+   * - Returns empty array if parse() was called with strict: true
+   *
+   * @example
+   * ```typescript
+   * const user = EntityUtils.parse(User, data);
+   * const problems = EntityUtils.problems(user);
+   * console.log(problems); // [Problem, ...]
+   * ```
+   */ static problems(instance) {
+        return problemsStorage.get(instance) || [];
+    }
+    /**
+   * Gets the raw input data that was used to create an entity instance
+   *
+   * @param instance - The entity instance
+   * @returns The raw input object, or undefined if not available
+   *
+   * @remarks
+   * - Only available for instances created via parse()
+   * - Returns a reference to the original input data (not a copy)
+   *
+   * @example
+   * ```typescript
+   * const user = EntityUtils.parse(User, { name: 'John', age: 30 });
+   * const rawInput = EntityUtils.getRawInput(user);
+   * console.log(rawInput); // { name: 'John', age: 30 }
+   * ```
+   */ static getRawInput(instance) {
+        return rawInputStorage.get(instance);
+    }
+    /**
+   * Gets all entity validator method names for an entity
+   * @private
+   */ static getEntityValidators(target) {
+        let currentProto;
+        if (target.constructor && target === target.constructor.prototype) {
+            currentProto = target;
+        } else {
+            currentProto = Object.getPrototypeOf(target);
+        }
+        const validators = [];
+        const seen = new Set();
+        while(currentProto && currentProto !== Object.prototype){
+            const protoValidators = Reflect.getOwnMetadata(ENTITY_VALIDATOR_METADATA_KEY, currentProto) || [];
+            for (const validator of protoValidators){
+                if (!seen.has(validator)) {
+                    seen.add(validator);
+                    validators.push(validator);
+                }
             }
-            return this.parse(typeConstructor, value);
+            currentProto = Object.getPrototypeOf(currentProto);
         }
-        throw new Error(`Property '${propertyKey}' has unknown type constructor. Supported types are: String, Number, Boolean, Date, BigInt, and @Entity() classes. Use passthrough: true to explicitly allow unknown types.`);
+        return validators;
     }
 }