@rtpaulino/entity 0.19.0 → 0.21.0

package/dist/lib/entity-utils.js

@@ -1,4 +1,4 @@
-/* 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';
+/* eslint-disable @typescript-eslint/no-unsafe-function-type */ /* eslint-disable @typescript-eslint/no-explicit-any */ import { ENTITY_METADATA_KEY, ENTITY_OPTIONS_METADATA_KEY, ENTITY_VALIDATOR_METADATA_KEY, PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
 import { getInjectedPropertyNames, getInjectedPropertyOptions } from './injected-property.js';
 import { EntityDI } from './entity-di.js';
 import { isEqualWith } from 'lodash-es';
@@ -48,6 +48,42 @@ export class EntityUtils {
         const constructor = Object.getPrototypeOf(obj).constructor;
         return Reflect.hasMetadata(ENTITY_METADATA_KEY, constructor);
     }
+    /**
+   * Gets the entity options for a given constructor
+   *
+   * @param entityOrClass - The entity class constructor or instance
+   * @returns EntityOptions object (empty object if no options are defined)
+   * @private
+   */ static getEntityOptions(entityOrClass) {
+        const constructor = typeof entityOrClass === 'function' ? entityOrClass : Object.getPrototypeOf(entityOrClass).constructor;
+        const options = Reflect.getMetadata(ENTITY_OPTIONS_METADATA_KEY, constructor);
+        return options ?? {};
+    }
+    /**
+   * Checks if a given entity is marked as a collection entity
+   *
+   * @param entityOrClass - The entity instance or class to check
+   * @returns true if the entity is a collection entity, false otherwise
+   *
+   * @example
+   * ```typescript
+   * @CollectionEntity()
+   * class Tags {
+   *   @ArrayProperty(() => String)
+   *   collection: string[];
+   * }
+   *
+   * const tags = new Tags({ collection: ['a', 'b'] });
+   * console.log(EntityUtils.isCollectionEntity(tags)); // true
+   * console.log(EntityUtils.isCollectionEntity(Tags)); // true
+   * ```
+   */ static isCollectionEntity(entityOrClass) {
+        if (!this.isEntity(entityOrClass)) {
+            return false;
+        }
+        const options = this.getEntityOptions(entityOrClass);
+        return options.collection === true;
+    }
     static sameEntity(a, b) {
         if (!this.isEntity(a) || !this.isEntity(b)) {
             return false;
@@ -161,7 +197,7 @@ export class EntityUtils {
    * Serializes an entity to a plain object, converting only properties decorated with @Property()
    *
    * @param entity - The entity instance to serialize
-   * @returns A plain object containing only the serialized decorated properties
+   * @returns A plain object containing only the serialized decorated properties, or an array for collection entities
    *
    * @remarks
    * Serialization rules:
@@ -174,6 +210,7 @@ export class EntityUtils {
    * - undefined values are excluded from the output
    * - null values are included in the output
    * - Circular references are not supported (will cause stack overflow)
+   * - Collection entities (@CollectionEntity) are unwrapped to just their array
    *
    * @example
    * ```typescript
@@ -205,8 +242,28 @@ export class EntityUtils {
    * //   address: { street: '123 Main St', city: 'Boston' },
    * //   createdAt: '2024-01-01T00:00:00.000Z'
    * // }
+   *
+   * @CollectionEntity()
+   * class Tags {
+   *   @ArrayProperty(() => String)
+   *   collection: string[];
+   * }
+   *
+   * const tags = new Tags({ collection: ['a', 'b'] });
+   * const json = EntityUtils.toJSON(tags);
+   * // ['a', 'b'] - unwrapped to array
    * ```
    */ static toJSON(entity) {
+        if (this.isCollectionEntity(entity)) {
+            const collectionPropertyOptions = this.getPropertyOptions(entity, 'collection');
+            if (!collectionPropertyOptions) {
+                throw new Error(`Collection entity 'collection' property is missing metadata`);
+            }
+            if (!collectionPropertyOptions.array) {
+                throw new Error(`Collection entity 'collection' property must be an array`);
+            }
+            return this.serializeValue(entity.collection, collectionPropertyOptions);
+        }
         const result = {};
         const keys = this.getPropertyKeys(entity);
         for (const key of keys){
@@ -234,16 +291,6 @@ export class EntityUtils {
         if (passthrough) {
             return value;
         }
-        if (options?.collection === true) {
-            if (!this.isEntity(value)) {
-                throw new Error(`Expected collection entity but received non-entity value`);
-            }
-            const collectionArray = value.collection;
-            if (!Array.isArray(collectionArray)) {
-                throw new Error(`Collection entity must have a 'collection' property that is an array`);
-            }
-            return collectionArray.map((item)=>this.serializeValue(item));
-        }
         if (Array.isArray(value)) {
             if (options?.serialize) {
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -269,49 +316,14 @@ export class EntityUtils {
         throw new Error(`Cannot serialize value of type '${typeof value}'. Use passthrough: true in @Property() to explicitly allow serialization of unknown types.`);
     }
     /**
-   * Deserializes a plain object to an entity instance
-   *
-   * @param entityClass - The entity class constructor. Must accept a data object parameter.
-   * @param plainObject - The plain object to deserialize
-   * @param parseOptions - Parse options (strict mode)
-   * @returns Promise resolving to a new instance of the entity with deserialized values
-   *
-   * @remarks
-   * Deserialization rules:
-   * - All @Property() decorators must include type metadata for parse() to work
-   * - Properties without type metadata will throw an error
-   * - Required properties (optional !== true) must be present and not null/undefined
-   * - Optional properties (optional === true) can be undefined or null
-   * - Arrays are supported with the array: true option
-   * - Nested entities are recursively deserialized
-   * - 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.getProblems()
-   * - Raw input data is accessible via EntityUtils.getRawInput()
-   *
-   * @example
-   * ```typescript
-   * @Entity()
-   * class User {
-   *   @Property({ type: () => String }) name!: string;
-   *   @Property({ type: () => Number }) age!: number;
-   *
-   *   constructor(data: Partial<User>) {
-   *     Object.assign(this, data);
-   *   }
-   * }
-   *
-   * const json = { name: 'John', age: 30 };
-   * const user = await EntityUtils.parse(User, json);
-   * const userStrict = await EntityUtils.parse(User, json, { strict: true });
-   * ```
-   */ static async parse(entityClass, plainObject, parseOptions = {}, knownProblems) {
+   * Internal parse implementation with extended options
+   * @private
+   */ static async _parseInternal(entityClass, plainObject, options = {}) {
+        if (this.isCollectionEntity(entityClass)) {
+            plainObject = {
+                collection: plainObject
+            };
+        }
         if (plainObject == null) {
             throw createValidationError(`Expects an object but received ${typeof plainObject}`);
         }
@@ -321,7 +333,9 @@ export class EntityUtils {
         if (typeof plainObject !== 'object') {
             throw createValidationError(`Expects an object but received ${typeof plainObject}`);
         }
-        const strict = parseOptions?.strict ?? false;
+        const strict = options.strict ?? false;
+        const skipDefaults = options.skipDefaults ?? false;
+        const skipMissing = options.skipMissing ?? false;
         const keys = this.getPropertyKeys(entityClass.prototype);
         const data = {};
         const hardProblems = [];
@@ -341,8 +355,11 @@ export class EntityUtils {
             }
             const isOptional = propertyOptions.optional === true;
             if (!(key in plainObject) || value == null) {
+                if (skipMissing) {
+                    continue;
+                }
                 let valueToSet = value;
-                if (propertyOptions.default !== undefined) {
+                if (!skipDefaults && propertyOptions.default !== undefined) {
                     valueToSet = typeof propertyOptions.default === 'function' ? await propertyOptions.default() : propertyOptions.default;
                 }
                 if (!isOptional && valueToSet == null) {
@@ -355,7 +372,10 @@ export class EntityUtils {
                 continue;
             }
             try {
-                data[key] = await this.deserializeValue(value, propertyOptions, parseOptions);
+                // Only pass strict to nested deserialization, not skipDefaults/skipMissing
+                data[key] = await this.deserializeValue(value, propertyOptions, {
+                    strict
+                });
             } catch (error) {
                 if (error instanceof ValidationError) {
                     const problems = prependPropertyPath(key, error);
@@ -370,13 +390,66 @@ export class EntityUtils {
                 }
             }
         }
+        return {
+            data,
+            hardProblems
+        };
+    }
+    /**
+   * Deserializes a plain object to an entity instance
+   *
+   * @param entityClass - The entity class constructor. Must accept a data object parameter.
+   * @param plainObject - The plain object to deserialize
+   * @param parseOptions - Parse options (strict mode)
+   * @returns Promise resolving to a new instance of the entity with deserialized values
+   *
+   * @remarks
+   * Deserialization rules:
+   * - All @Property() decorators must include type metadata for parse() to work
+   * - Properties without type metadata will throw an error
+   * - Required properties (optional !== true) must be present and not null/undefined
+   * - Optional properties (optional === true) can be undefined or null
+   * - Arrays are supported with the array: true option
+   * - Nested entities are recursively deserialized
+   * - 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.getProblems()
+   * - Raw input data is accessible via EntityUtils.getRawInput()
+   *
+   * @example
+   * ```typescript
+   * @Entity()
+   * class User {
+   *   @Property({ type: () => String }) name!: string;
+   *   @Property({ type: () => Number }) age!: number;
+   *
+   *   constructor(data: Partial<User>) {
+   *     Object.assign(this, data);
+   *   }
+   * }
+   *
+   * const json = { name: 'John', age: 30 };
+   * const user = await EntityUtils.parse(User, json);
+   * const userStrict = await EntityUtils.parse(User, json, { strict: true });
+   * ```
+   */ static async parse(entityClass, plainObject, parseOptions = {}) {
+        const strict = parseOptions?.strict ?? false;
+        const { data, hardProblems } = await this._parseInternal(entityClass, plainObject, {
+            strict
+        });
         if (hardProblems.length > 0) {
             throw new ValidationError(hardProblems);
         }
         await this.addInjectedDependencies(data, entityClass.prototype);
         const instance = new entityClass(data);
         rawInputStorage.set(instance, plainObject);
-        const problems = await this.validate(instance, knownProblems);
+        const problems = await this.validate(instance);
         if (problems.length > 0 && strict) {
             throw new ValidationError(problems);
         }
@@ -440,6 +513,119 @@ export class EntityUtils {
         }
     }
     /**
+   * Partially deserializes a plain object, returning a plain object with only present properties
+   *
+   * @param entityClass - The entity class constructor
+   * @param plainObject - The plain object to deserialize
+   * @param options - Options with strict mode
+   * @returns Promise resolving to a plain object with deserialized properties (Partial<T>)
+   *
+   * @remarks
+   * Differences from parse():
+   * - Returns a plain object, not an entity instance
+   * - Ignores missing properties (does not include them in result)
+   * - Does NOT apply default values to missing properties
+   * - When strict: false (default), properties with HARD problems are excluded from result but problems are tracked
+   * - When strict: true, any HARD problem throws ValidationError
+   * - Nested entities/arrays are still fully deserialized and validated as normal
+   *
+   * @example
+   * ```typescript
+   * @Entity()
+   * class User {
+   *   @Property({ type: () => String }) name!: string;
+   *   @Property({ type: () => Number, default: 0 }) age!: number;
+   *
+   *   constructor(data: Partial<User>) {
+   *     Object.assign(this, data);
+   *   }
+   * }
+   *
+   * const partial = await EntityUtils.partialParse(User, { name: 'John' });
+   * // partial = { name: 'John' } (age is not included, default not applied)
+   *
+   * const partialWithError = await EntityUtils.partialParse(User, { name: 'John', age: 'invalid' });
+   * // partialWithError = { name: 'John' } (age excluded due to HARD problem)
+   * // Access problems via second return value
+   * ```
+   */ static async partialParse(entityClass, plainObject, options = {}) {
+        const result = await this.safePartialParse(entityClass, plainObject, options);
+        if (!result.success) {
+            throw new ValidationError(result.problems);
+        }
+        return result.data;
+    }
+    /**
+   * Safely performs partial deserialization without throwing errors
+   *
+   * @param entityClass - The entity class constructor
+   * @param plainObject - The plain object to deserialize
+   * @param options - Options with strict mode
+   * @returns Promise resolving to a result object with success flag, partial data, and problems
+   *
+   * @remarks
+   * Similar to partialParse() but returns a result object instead of throwing errors:
+   * - On success with strict: true - returns { success: true, data: Partial<T>, problems: [] }
+   * - On success with strict: false - returns { success: true, data: Partial<T>, problems: [...] } (includes hard problems for excluded properties)
+   * - On failure (strict mode only) - returns { success: false, data: undefined, problems: [...] }
+   *
+   * All partial deserialization rules from partialParse() apply.
+   * See partialParse() documentation for detailed behavior.
+   *
+   * @example
+   * ```typescript
+   * @Entity()
+   * class User {
+   *   @Property({ type: () => String }) name!: string;
+   *   @Property({ type: () => Number }) age!: number;
+   *
+   *   constructor(data: Partial<User>) {
+   *     Object.assign(this, data);
+   *   }
+   * }
+   *
+   * const result = await EntityUtils.safePartialParse(User, { name: 'John', age: 'invalid' });
+   * if (result.success) {
+   *   console.log(result.data); // { name: 'John' }
+   *   console.log(result.problems); // [Problem for age property]
+   * } else {
+   *   console.log(result.problems); // Hard problems (only in strict mode)
+   * }
+   * ```
+   */ static async safePartialParse(entityClass, plainObject, options) {
+        const strict = options?.strict ?? false;
+        const { data, hardProblems } = await this._parseInternal(entityClass, plainObject, {
+            strict,
+            skipDefaults: true,
+            skipMissing: true
+        });
+        if (strict && hardProblems.length > 0) {
+            return {
+                success: false,
+                data: undefined,
+                problems: hardProblems
+            };
+        }
+        const propertyProblems = await this.validateProperties(data, entityClass.prototype);
+        const validationProblems = [
+            ...hardProblems,
+            ...propertyProblems
+        ];
+        if (strict && propertyProblems.length > 0) {
+            return {
+                success: false,
+                data: undefined,
+                problems: validationProblems
+            };
+        }
+        this.setProblems(data, validationProblems);
+        return {
+            success: true,
+            data: data,
+            problems: validationProblems
+        };
+    }
+    /**
    * Updates an entity instance with new values, respecting preventUpdates flags on properties
    *
    * @param instance - The entity instance to update. Must be an Entity.
@@ -567,25 +753,7 @@ export class EntityUtils {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         const typeConstructor = options.type();
         const isArray = options.array === true;
-        const isCollection = options.collection === true;
         const isSparse = options.sparse === true;
-        const problems = [];
-        if (isCollection) {
-            if (!this.isEntity(typeConstructor)) {
-                throw createValidationError(`Collection property type must be an @Entity() class`);
-            }
-            if (!Array.isArray(value)) {
-                problems.push(new Problem({
-                    message: `Collection property expects an array but received ${typeof value}`
-                }));
-            }
-            const collectionInstance = await this.parse(typeConstructor, {
-                collection: Array.isArray(value) ? value : []
-            }, parseOptions, problems);
-            // override raw input to be the array only
-            rawInputStorage.set(collectionInstance, value);
-            return collectionInstance;
-        }
         if (isArray) {
             if (!Array.isArray(value)) {
                 throw createValidationError(`Expects an array but received ${typeof value}`);
@@ -638,9 +806,6 @@ export class EntityUtils {
             return deserializePrimitive(value, typeConstructor);
         }
         if (this.isEntity(typeConstructor)) {
-            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-                throw createValidationError(`Expects an object but received ${typeof value}`);
-            }
             return await this.parse(typeConstructor, value, parseOptions);
         }
         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.`);
@@ -711,6 +876,24 @@ export class EntityUtils {
         }
         return problems;
     }
+    /**
+   * Validates all properties on an object (entity instance or plain object)
+   * @private
+   */ static async validateProperties(dataOrInstance, prototype) {
+        const problems = [];
+        const keys = Object.keys(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);
+                    problems.push(...validationProblems);
+                }
+            }
+        }
+        return problems;
+    }
     static async addInjectedDependencies(data, prototype) {
         const injectedPropertyNames = getInjectedPropertyNames(prototype);
         if (injectedPropertyNames.length === 0) {
@@ -742,22 +925,13 @@ export class EntityUtils {
    * const problems = await EntityUtils.validate(user);
    * console.log(problems); // [Problem, Problem, ...]
    * ```
-   */ static async validate(instance, knownProblems = []) {
+   */ 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);
-                }
-            }
-        }
+        const propertyProblems = await this.validateProperties(instance, instance);
+        problems.push(...propertyProblems);
         const entityValidators = this.getEntityValidators(instance);
         for (const validatorMethod of entityValidators){
             const validatorProblems = await instance[validatorMethod]();
@@ -765,12 +939,8 @@ export class EntityUtils {
                 problems.push(...validatorProblems);
             }
         }
-        const allProblems = [
-            ...knownProblems,
-            ...problems
-        ];
-        EntityUtils.setProblems(instance, allProblems);
-        return allProblems;
+        EntityUtils.setProblems(instance, problems);
+        return problems;
     }
     /**
    * Gets the validation problems for an entity instance