@rtpaulino/entity 0.22.0 → 0.23.1

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import 'reflect-metadata';
 export * from './lib/entity.js';
 export * from './lib/entity-utils.js';
 export * from './lib/entity-di.js';
+export * from './lib/entity-registry.js';
 export * from './lib/types.js';
 export * from './lib/property.js';
 export * from './lib/validation-error.js';

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,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,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,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ import 'reflect-metadata';
 export * from './lib/entity.js';
 export * from './lib/entity-utils.js';
 export * from './lib/entity-di.js';
+export * from './lib/entity-registry.js';
 export * from './lib/types.js';
 export * from './lib/property.js';
 export * from './lib/validation-error.js';

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/entity-di.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';\nexport * from './lib/validators.js';\nexport * from './lib/zod-property.js';\nexport * from './lib/injected-property.js';\n"],"names":[],"mappings":"AAAA,OAAO,mBAAmB;AAE1B,cAAc,kBAAkB;AAChC,cAAc,wBAAwB;AACtC,cAAc,qBAAqB;AACnC,cAAc,iBAAiB;AAC/B,cAAc,oBAAoB;AAClC,cAAc,4BAA4B;AAC1C,cAAc,mBAAmB;AACjC,cAAc,4BAA4B;AAC1C,cAAc,mCAAmC;AACjD,cAAc,sBAAsB;AACpC,cAAc,wBAAwB;AACtC,cAAc,6BAA6B"}
+{"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/entity-di.js';\nexport * from './lib/entity-registry.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';\nexport * from './lib/validators.js';\nexport * from './lib/zod-property.js';\nexport * from './lib/injected-property.js';\n"],"names":[],"mappings":"AAAA,OAAO,mBAAmB;AAE1B,cAAc,kBAAkB;AAChC,cAAc,wBAAwB;AACtC,cAAc,qBAAqB;AACnC,cAAc,2BAA2B;AACzC,cAAc,iBAAiB;AAC/B,cAAc,oBAAoB;AAClC,cAAc,4BAA4B;AAC1C,cAAc,mBAAmB;AACjC,cAAc,4BAA4B;AAC1C,cAAc,mCAAmC;AACjD,cAAc,sBAAsB;AACpC,cAAc,wBAAwB;AACtC,cAAc,6BAA6B"}

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

@@ -0,0 +1,32 @@
+/**
+ * Registry for entity classes decorated with @Entity()
+ * Stores entity constructors by name for discriminated entity deserialization
+ */
+export declare class EntityRegistry {
+    private static readonly registry;
+    /**
+     * Registers an entity class with a name
+     * @param name - The name to register the entity under
+     * @param entityClass - The entity class constructor
+     * @throws Error if an entity with this name is already registered
+     */
+    static register(name: string, entityClass: Function): void;
+    /**
+     * Gets an entity class by name
+     * @param name - The name of the entity to retrieve
+     * @returns The entity class constructor, or undefined if not found
+     */
+    static get(name: string): Function | undefined;
+    /**
+     * Checks if an entity with the given name is registered
+     * @param name - The name to check
+     * @returns true if an entity with this name is registered
+     */
+    static has(name: string): boolean;
+    /**
+     * Gets all registered entity names
+     * @returns Array of all registered entity names
+     */
+    static getAllNames(): string[];
+}
+//# sourceMappingURL=entity-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-registry.d.ts","sourceRoot":"","sources":["../../src/lib/entity-registry.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IAE/D;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI;IAW1D;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI9C;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;;OAGG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM,EAAE;CAG/B"}

package/dist/lib/entity-registry.js

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */ /* eslint-disable @typescript-eslint/no-unsafe-function-type */ /**
+ * Registry for entity classes decorated with @Entity()
+ * Stores entity constructors by name for discriminated entity deserialization
+ */ export class EntityRegistry {
+    static{
+        this.registry = new Map();
+    }
+    /**
+   * Registers an entity class with a name
+   * @param name - The name to register the entity under
+   * @param entityClass - The entity class constructor
+   * @throws Error if an entity with this name is already registered
+   */ static register(name, entityClass) {
+        const existing = this.registry.get(name);
+        if (existing && existing !== entityClass) {
+            throw new Error(`Entity name conflict: An entity with name '${name}' is already registered. ` + `Existing: ${existing.name}, New: ${entityClass.name}`);
+        }
+        this.registry.set(name, entityClass);
+    }
+    /**
+   * Gets an entity class by name
+   * @param name - The name of the entity to retrieve
+   * @returns The entity class constructor, or undefined if not found
+   */ static get(name) {
+        return this.registry.get(name);
+    }
+    /**
+   * Checks if an entity with the given name is registered
+   * @param name - The name to check
+   * @returns true if an entity with this name is registered
+   */ static has(name) {
+        return this.registry.has(name);
+    }
+    /**
+   * Gets all registered entity names
+   * @returns Array of all registered entity names
+   */ static getAllNames() {
+        return Array.from(this.registry.keys());
+    }
+}
+
+//# sourceMappingURL=entity-registry.js.map

package/dist/lib/entity-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/entity-registry.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\n/* eslint-disable @typescript-eslint/no-unsafe-function-type */\n\n/**\n * Registry for entity classes decorated with @Entity()\n * Stores entity constructors by name for discriminated entity deserialization\n */\nexport class EntityRegistry {\n  private static readonly registry = new Map<string, Function>();\n\n  /**\n   * Registers an entity class with a name\n   * @param name - The name to register the entity under\n   * @param entityClass - The entity class constructor\n   * @throws Error if an entity with this name is already registered\n   */\n  static register(name: string, entityClass: Function): void {\n    const existing = this.registry.get(name);\n    if (existing && existing !== entityClass) {\n      throw new Error(\n        `Entity name conflict: An entity with name '${name}' is already registered. ` +\n          `Existing: ${existing.name}, New: ${entityClass.name}`,\n      );\n    }\n    this.registry.set(name, entityClass);\n  }\n\n  /**\n   * Gets an entity class by name\n   * @param name - The name of the entity to retrieve\n   * @returns The entity class constructor, or undefined if not found\n   */\n  static get(name: string): Function | undefined {\n    return this.registry.get(name);\n  }\n\n  /**\n   * Checks if an entity with the given name is registered\n   * @param name - The name to check\n   * @returns true if an entity with this name is registered\n   */\n  static has(name: string): boolean {\n    return this.registry.has(name);\n  }\n\n  /**\n   * Gets all registered entity names\n   * @returns Array of all registered entity names\n   */\n  static getAllNames(): string[] {\n    return Array.from(this.registry.keys());\n  }\n}\n"],"names":["EntityRegistry","registry","Map","register","name","entityClass","existing","get","Error","set","has","getAllNames","Array","from","keys"],"mappings":"AAAA,qDAAqD,GACrD,6DAA6D,GAE7D;;;CAGC,GACD,OAAO,MAAMA;;aACaC,WAAW,IAAIC;;IAEvC;;;;;GAKC,GACD,OAAOC,SAASC,IAAY,EAAEC,WAAqB,EAAQ;QACzD,MAAMC,WAAW,IAAI,CAACL,QAAQ,CAACM,GAAG,CAACH;QACnC,IAAIE,YAAYA,aAAaD,aAAa;YACxC,MAAM,IAAIG,MACR,CAAC,2CAA2C,EAAEJ,KAAK,yBAAyB,CAAC,GAC3E,CAAC,UAAU,EAAEE,SAASF,IAAI,CAAC,OAAO,EAAEC,YAAYD,IAAI,EAAE;QAE5D;QACA,IAAI,CAACH,QAAQ,CAACQ,GAAG,CAACL,MAAMC;IAC1B;IAEA;;;;GAIC,GACD,OAAOE,IAAIH,IAAY,EAAwB;QAC7C,OAAO,IAAI,CAACH,QAAQ,CAACM,GAAG,CAACH;IAC3B;IAEA;;;;GAIC,GACD,OAAOM,IAAIN,IAAY,EAAW;QAChC,OAAO,IAAI,CAACH,QAAQ,CAACS,GAAG,CAACN;IAC3B;IAEA;;;GAGC,GACD,OAAOO,cAAwB;QAC7B,OAAOC,MAAMC,IAAI,CAAC,IAAI,CAACZ,QAAQ,CAACa,IAAI;IACtC;AACF"}

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

@@ -30,6 +30,24 @@ export declare class EntityUtils {
      * @private
      */
     private static getEntityOptions;
+    /**
+     * Gets the registered name for an entity class or instance
+     *
+     * @param entityOrClass - The entity class constructor or instance
+     * @returns The entity name, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * @Entity({ name: 'CustomUser' })
+     * class User {
+     *   name: string;
+     * }
+     *
+     * console.log(EntityUtils.getEntityName(User)); // 'CustomUser'
+     * console.log(EntityUtils.getEntityName(new User())); // 'CustomUser'
+     * ```
+     */
+    static getEntityName(entityOrClass: unknown): string | undefined;
     /**
      * Checks if a given entity is marked as a collection entity
      *
@@ -70,6 +88,15 @@ export declare class EntityUtils {
      * ```
      */
     static isStringifiable(entityOrClass: unknown): boolean;
+    /**
+     * Gets the "wrapper" property name for entities that act as transparent wrappers.
+     * When set, this property name is excluded from error paths during validation.
+     *
+     * @param entityOrClass - The entity instance or class to check
+     * @returns The wrapper property name, or undefined if not a wrapper entity
+     * @private
+     */
+    private static getWrapperPropertyName;
     static sameEntity(a: object, b: object): boolean;
     static getPropertyKeys(target: object): string[];
     static getPropertyOptions(target: object, propertyKey: string): PropertyOptions | undefined;
@@ -407,12 +434,22 @@ export declare class EntityUtils {
      * @private
      */
     private static deserializeSingleValue;
+    /**
+     * Deserializes a discriminated entity value by reading the discriminator and looking up the entity class
+     * @private
+     */
+    private static deserializeDiscriminatedValue;
     /**
      * Validates a property value by running validators and nested entity validation.
      * Prepends the property path to all returned problems.
      * @private
      */
     private static validatePropertyValue;
+    /**
+     * Checks if an array contains any entity elements
+     * @private
+     */
+    private static hasEntityElements;
     /**
      * Runs property validators for a given property value
      * @private

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":"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"}
+{"version":3,"file":"entity-utils.d.ts","sourceRoot":"","sources":["../../src/lib/entity-utils.ts"],"names":[],"mappings":"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"}

package/dist/lib/entity-utils.js

@@ -4,9 +4,10 @@ import { EntityDI } from './entity-di.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 { prependArrayIndex, prependPropertyPath, createValidationError } from './validation-utils.js';
 import { isPrimitiveConstructor, deserializePrimitive } from './primitive-deserializers.js';
 import { ok } from 'assert';
+import { EntityRegistry } from './entity-registry.js';
 /**
  * WeakMap to store validation problems for entity instances
  */ const problemsStorage = new WeakMap();
@@ -60,6 +61,29 @@ export class EntityUtils {
         return options ?? {};
     }
     /**
+   * Gets the registered name for an entity class or instance
+   *
+   * @param entityOrClass - The entity class constructor or instance
+   * @returns The entity name, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * @Entity({ name: 'CustomUser' })
+   * class User {
+   *   name: string;
+   * }
+   *
+   * console.log(EntityUtils.getEntityName(User)); // 'CustomUser'
+   * console.log(EntityUtils.getEntityName(new User())); // 'CustomUser'
+   * ```
+   */ static getEntityName(entityOrClass) {
+        if (!this.isEntity(entityOrClass)) {
+            return undefined;
+        }
+        const options = this.getEntityOptions(entityOrClass);
+        return options.name;
+    }
+    /**
    * Checks if a given entity is marked as a collection entity
    *
    * @param entityOrClass - The entity instance or class to check
@@ -109,6 +133,19 @@ export class EntityUtils {
         const options = this.getEntityOptions(entityOrClass);
         return options.stringifiable === true;
     }
+    /**
+   * Gets the "wrapper" property name for entities that act as transparent wrappers.
+   * When set, this property name is excluded from error paths during validation.
+   *
+   * @param entityOrClass - The entity instance or class to check
+   * @returns The wrapper property name, or undefined if not a wrapper entity
+   * @private
+   */ static getWrapperPropertyName(entityOrClass) {
+        if (!this.isEntity(entityOrClass)) {
+            return undefined;
+        }
+        return this.getEntityOptions(entityOrClass).wrapperProperty;
+    }
     static sameEntity(a, b) {
         if (!this.isEntity(a) || !this.isEntity(b)) {
             return false;
@@ -334,7 +371,7 @@ export class EntityUtils {
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 return value.map((item)=>options.serialize(item));
             }
-            return value.map((item)=>this.serializeValue(item));
+            return value.map((item)=>this.serializeValue(item, options));
         }
         if (options?.serialize) {
             return options.serialize(value);
@@ -346,7 +383,25 @@ export class EntityUtils {
             return value.toString();
         }
         if (this.isEntity(value)) {
-            return this.toJSON(value);
+            const serialized = this.toJSON(value);
+            // If this is a discriminated entity property, add the discriminator inline
+            if (options?.discriminated === true) {
+                const discriminatorProperty = options.discriminatorProperty;
+                ok(discriminatorProperty, 'Discriminator property must be defined');
+                const entityClass = Object.getPrototypeOf(value).constructor;
+                const entityName = this.getEntityName(entityClass);
+                if (!entityName) {
+                    throw new Error(`Cannot serialize discriminated entity: Entity class '${entityClass.name}' is not registered. Ensure it's decorated with @Entity().`);
+                }
+                if (typeof serialized !== 'object' || Array.isArray(serialized) || serialized === null) {
+                    throw new Error(`Cannot serialize discriminated entity: Expected serialized value to be an object.`);
+                }
+                return {
+                    ...serialized,
+                    [discriminatorProperty]: entityName
+                };
+            }
+            return serialized;
         }
         if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
             return value;
@@ -357,13 +412,10 @@ export class EntityUtils {
    * Internal parse implementation with extended options
    * @private
    */ static async _parseInternal(entityClass, plainObject, options = {}) {
-        if (this.isStringifiable(entityClass)) {
-            plainObject = {
-                value: plainObject
-            };
-        } else if (this.isCollectionEntity(entityClass)) {
+        const wrapperPropertyName = this.getWrapperPropertyName(entityClass);
+        if (wrapperPropertyName) {
             plainObject = {
-                collection: plainObject
+                [wrapperPropertyName]: plainObject
             };
         }
         if (plainObject == null) {
@@ -420,11 +472,16 @@ export class EntityUtils {
                 });
             } catch (error) {
                 if (error instanceof ValidationError) {
-                    const problems = prependPropertyPath(key, error);
-                    hardProblems.push(...problems);
+                    const isWrapperProperty = wrapperPropertyName === key;
+                    if (isWrapperProperty) {
+                        hardProblems.push(...error.problems);
+                    } else {
+                        const problems = prependPropertyPath(key, error.problems);
+                        hardProblems.push(...problems);
+                    }
                 } else if (error instanceof Error) {
                     hardProblems.push(new Problem({
-                        property: key,
+                        property: wrapperPropertyName === key ? '' : key,
                         message: error.message
                     }));
                 } else {
@@ -792,10 +849,9 @@ export class EntityUtils {
    * Deserializes a single value according to the type metadata
    * @private
    */ static async deserializeValue(value, options, parseOptions) {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const typeConstructor = options.type();
         const isArray = options.array === true;
         const isSparse = options.sparse === true;
+        const isDiscriminated = options.discriminated === true;
         if (isArray) {
             if (!Array.isArray(value)) {
                 throw createValidationError(`Expects an array but received ${typeof value}`);
@@ -816,7 +872,11 @@ export class EntityUtils {
                     try {
                         if (options.deserialize) {
                             result.push(options.deserialize(item));
+                        } else if (isDiscriminated) {
+                            result.push(await this.deserializeDiscriminatedValue(item, options));
                         } else {
+                            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                            const typeConstructor = options.type();
                             result.push(await this.deserializeSingleValue(item, typeConstructor, parseOptions));
                         }
                     } catch (error) {
@@ -837,6 +897,11 @@ export class EntityUtils {
         if (options.deserialize) {
             return options.deserialize(value);
         }
+        if (isDiscriminated) {
+            return await this.deserializeDiscriminatedValue(value, options);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const typeConstructor = options.type();
         return await this.deserializeSingleValue(value, typeConstructor, parseOptions);
     }
     /**
@@ -853,6 +918,28 @@ export class EntityUtils {
         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.`);
     }
     /**
+   * Deserializes a discriminated entity value by reading the discriminator and looking up the entity class
+   * @private
+   */ static async deserializeDiscriminatedValue(value, options) {
+        if (value == null) {
+            throw createValidationError(`Cannot deserialize discriminated entity from null or undefined`);
+        }
+        if (typeof value !== 'object' || Array.isArray(value)) {
+            throw createValidationError(`Discriminated entity must be an object, received ${typeof value}`);
+        }
+        const discriminatorProperty = options.discriminatorProperty;
+        ok(discriminatorProperty, 'Discriminator property must be defined');
+        const discriminatorValue = value[discriminatorProperty];
+        if (typeof discriminatorValue !== 'string' || discriminatorValue.trim() === '') {
+            throw createValidationError(`Missing or invalid discriminator property '${discriminatorProperty}'. Expected a non-empty string.`);
+        }
+        const entityClass = EntityRegistry.get(discriminatorValue);
+        if (!entityClass) {
+            throw createValidationError(`Unknown entity type '${discriminatorValue}'. No entity registered with this name.`);
+        }
+        return await this.parse(entityClass, value, {});
+    }
+    /**
    * Validates a property value by running validators and nested entity validation.
    * Prepends the property path to all returned problems.
    * @private
@@ -863,24 +950,32 @@ export class EntityUtils {
                 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
-                    }));
+                if (validatorProblems.length > 0) {
+                    const prepended = prependPropertyPath(propertyPath, validatorProblems);
+                    problems.push(...prepended);
                 }
             }
         }
         if (EntityUtils.isEntity(value)) {
             const existingProblems = problemsStorage.get(value);
             const nestedProblems = existingProblems && existingProblems.length > 0 ? existingProblems : await EntityUtils.validate(value);
-            const prependedProblems = prependPropertyPath(propertyPath, new ValidationError(nestedProblems));
-            problems.push(...prependedProblems);
+            if (nestedProblems.length > 0) {
+                const prepended = prependPropertyPath(propertyPath, nestedProblems);
+                problems.push(...prepended);
+            }
         }
         return problems;
     }
     /**
+   * Checks if an array contains any entity elements
+   * @private
+   */ static hasEntityElements(value) {
+        if (!Array.isArray(value)) {
+            return false;
+        }
+        return value.some((element)=>this.isEntity(element));
+    }
+    /**
    * Runs property validators for a given property value
    * @private
    */ static async runPropertyValidators(key, value, options) {
@@ -897,15 +992,13 @@ export class EntityUtils {
                 const validatorProblems = await validator({
                     value
                 });
-                for (const problem of validatorProblems){
-                    problems.push(new Problem({
-                        property: combinePropertyPaths(key, problem.property),
-                        message: problem.message
-                    }));
+                if (validatorProblems.length > 0) {
+                    const prepended = prependPropertyPath(key, validatorProblems);
+                    problems.push(...prepended);
                 }
             }
             const validators = options.validators || [];
-            if (validators.length > 0) {
+            if (validators.length > 0 || this.hasEntityElements(value)) {
                 for(let i = 0; i < value.length; i++){
                     const element = value[i];
                     if (element !== null && element !== undefined) {
@@ -924,12 +1017,14 @@ export class EntityUtils {
    */ static async validateProperties(dataOrInstance, prototype) {
         const problems = [];
         const keys = Object.keys(dataOrInstance);
+        const wrapperProperty = this.getWrapperPropertyName(dataOrInstance);
         for (const key of keys){
             const options = this.getPropertyOptions(prototype, key);
             if (options) {
                 const value = dataOrInstance[key];
                 if (value != null) {
-                    const validationProblems = await this.runPropertyValidators(key, value, options);
+                    const propertyPath = wrapperProperty === key ? '' : key;
+                    const validationProblems = await this.runPropertyValidators(propertyPath, value, options);
                     problems.push(...validationProblems);
                 }
             }