merge: release 0.2.0

Author: NoNameProvided

.travis.yml

@@ -2,7 +2,6 @@ language: node_js
 node_js:
   - stable
   - 8
-  - 6
 
 after_success:
   - bash <(curl -s https://codecov.io/bash)

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog and release notes
 
+### 0.2.0 [BREAKING CHANGE]
+
+#### Added
+
+- add documentation for using `Set`s and `Map`s
+- add opotion to pass a discriminator function to convert values into different types based on custom conditions
+- added support for polymorphism based on a named type property
+
+#### Fixed
+
+- fix bug when transforming `null` values as primitives
+
 ### 0.1.10
 
 #### Fixed

README.md

@@ -267,6 +267,78 @@ let album = plainToClass(Album, albumJson);
 // now album is Album object with Photo objects inside
 ```
 
+### Providing more than one type option
+
+In case the nested object can be of different types, you can provide an additional options object,
+that specifies a discriminator. The discriminator option must define a `property` that holds the sub
+type name for the object and the possible `subTypes`, the nested object can converted to. A sub type
+has a `value`, that holds the constructor of the Type and the `name`, that can match with the `property`
+of the discriminator.
+
+Lets say we have an album that has a top photo. But this photo can be of certain different types.
+And we are trying to convert album plain object to class object. The plain object input has to define
+the additional property `__type`. This property is removed during transformation by default:
+
+**JSON input**:
+```json
+{
+    "id": 1,
+    "name": "foo",
+    "topPhoto": {
+        "id": 9,
+        "filename": "cool_wale.jpg",
+        "depth": 1245,
+        "__type": "underwater"
+    }
+}
+```
+
+```typescript
+import {Type, plainToClass} from "class-transformer";
+
+export abstract class Photo {
+    id: number;
+    filename: string;
+}
+
+export class Landscape extends Photo {
+    panorama: boolean;
+}
+
+export class Portrait extends Photo {
+    person: Person;
+}
+
+export class UnderWater extends Photo {
+    depth: number;
+}
+
+export class Album {
+
+    id: number;
+    name: string;
+
+    @Type(() => Photo, {
+        discriminator: {
+            property: "__type",
+            subTypes: [
+                { value: Landscape, name: "landscape" },
+                { value: Portrait, name: "portrait" },
+                { value: UnderWater, name: "underwater" }
+            ]
+        }
+    })
+    topPhoto: Landscape | Portrait | UnderWater;
+
+}
+
+let album = plainToClass(Album, albumJson);
+// now album is Album object with a UnderWater object without `__type` property.
+```
+
+Hint: The same applies for arrays with different sub types. Moreover you can specify `keepDiscriminatorProperty: true`
+in the options to keep the discriminator property also inside your resulting class.
+
 ## Exposing getters and method return values
 
 You can expose what your getter or method return by setting a `@Expose()` decorator to those getters or methods:
@@ -565,6 +637,29 @@ export class Photo {
 
 Library will handle proper transformation automatically.
 
+ES6 collections `Set` and `Map` also require the `@Type` decorator:
+
+```typescript
+export class Skill {
+    name: string;
+}
+
+export class Weapon {
+    name: string;
+    range: number;
+}
+
+export class Player {
+    name: string;
+
+    @Type(() => Skill)
+    skills: Set<Skill>;
+
+    @Type(() => Weapon)
+    weapons: Map<string, Weapon>;
+}
+```
+
 ## Additional data transformation
 
 ### Basic usage
@@ -611,6 +706,7 @@ The `@Transform` decorator is given more arguments to let you configure how you
 |--------------------|------------------------------------------|---------------------------------------------|
 | `@TransformClassToPlain` | `@TransformClassToPlain({ groups: ["user"] })` | Transform the method return with classToPlain and expose the properties on the class.
 | `@TransformClassToClass` | `@TransformClassToClass({ groups: ["user"] })` | Transform the method return with classToClass and expose the properties on the class.
+| `@TransformPlainToClass` | `@TransformPlainToClass(User, { groups: ["user"] })` | Transform the method return with plainToClass and expose the properties on the class.
 
 The above decorators accept one optional argument:
 ClassTransformOptions - The transform options like groups, version, name

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "class-transformer",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors",
   "license": "MIT",
   "readmeFilename": "README.md",

package.json

@@ -1,6 +1,7 @@
-import {ClassTransformOptions} from "./ClassTransformOptions";
-import {defaultMetadataStorage} from "./storage";
-import {TypeOptions} from "./metadata/ExposeExcludeOptions";
+import { ClassTransformOptions } from "./ClassTransformOptions";
+import { defaultMetadataStorage } from "./storage";
+import { TypeHelpOptions, Discriminator, TypeOptions } from "./metadata/ExposeExcludeOptions";
+import { TypeMetadata } from "./metadata/TypeMetadata";
 
 export enum TransformationType {
     PLAIN_TO_CLASS,
@@ -14,33 +15,52 @@ export class TransformOperationExecutor {
     // Private Properties
     // -------------------------------------------------------------------------
 
-    private transformedTypesMap = new Map<Object, {level: number, object: Object}>();
+    private recursionStack = new Set<Object>();
 
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------
 
     constructor(private transformationType: TransformationType,
-                private options: ClassTransformOptions) {
+        private options: ClassTransformOptions) {
     }
 
     // -------------------------------------------------------------------------
     // Public Methods
     // -------------------------------------------------------------------------
 
-    transform(source: Object|Object[]|any,
-              value: Object|Object[]|any,
-              targetType: Function,
-              arrayType: Function,
-              isMap: boolean,
-              level: number = 0) {
+    transform(source: Object | Object[] | any,
+        value: Object | Object[] | any,
+        targetType: Function | TypeMetadata,
+        arrayType: Function,
+        isMap: boolean,
+        level: number = 0) {
 
-        if (value instanceof Array || value instanceof Set) {
+        if (Array.isArray(value) || value instanceof Set) {
             const newValue = arrayType && this.transformationType === TransformationType.PLAIN_TO_CLASS ? new (arrayType as any)() : [];
             (value as any[]).forEach((subValue, index) => {
                 const subSource = source ? source[index] : undefined;
-                if (!this.options.enableCircularCheck || !this.isCircular(subValue, level)) {
-                    const value = this.transform(subSource, subValue, targetType, undefined, subValue instanceof Map, level + 1);
+                if (!this.options.enableCircularCheck || !this.isCircular(subValue)) {
+                    let realTargetType;
+                    if (typeof targetType !== "function" && targetType && targetType.options && targetType.options.discriminator && targetType.options.discriminator.property && targetType.options.discriminator.subTypes) {
+                        if (this.transformationType === TransformationType.PLAIN_TO_CLASS) {
+                            realTargetType = targetType.options.discriminator.subTypes.find((subType) => subType.name === subValue[(targetType as { options: TypeOptions }).options.discriminator.property]);
+                            const options: TypeHelpOptions = { newObject: newValue, object: subValue, property: undefined };
+                            const newType = targetType.typeFunction(options);
+                            realTargetType === undefined ? realTargetType = newType : realTargetType = realTargetType.value;
+                            if (!targetType.options.keepDiscriminatorProperty) delete subValue[targetType.options.discriminator.property];
+                        }
+                        if (this.transformationType === TransformationType.CLASS_TO_CLASS) {
+                            realTargetType = subValue.constructor;
+                        }
+                        if (this.transformationType === TransformationType.CLASS_TO_PLAIN) {
+                            subValue[targetType.options.discriminator.property] = targetType.options.discriminator.subTypes.find((subType) => subType.value === subValue.constructor).name;
+                        }
+                    } else {
+                        realTargetType = targetType;
+                    }
+                    const value = this.transform(subSource, subValue, realTargetType, undefined, subValue instanceof Map, level + 1);
+
                     if (newValue instanceof Set) {
                         newValue.add(value);
                     } else {
@@ -55,14 +75,19 @@ export class TransformOperationExecutor {
                 }
             });
             return newValue;
-
         } else if (targetType === String && !isMap) {
+            if (value === null || value === undefined)
+                return value;
             return String(value);
 
         } else if (targetType === Number && !isMap) {
+            if (value === null || value === undefined)
+                return value;
             return Number(value);
 
         } else if (targetType === Boolean && !isMap) {
+            if (value === null || value === undefined)
+                return value;
             return Boolean(value);
 
         } else if ((targetType === Date || value instanceof Date) && !isMap) {
@@ -82,10 +107,10 @@ export class TransformOperationExecutor {
 
             if (this.options.enableCircularCheck) {
                 // add transformed type to prevent circular references
-                this.transformedTypesMap.set(value, {level: level, object: value});
+                this.recursionStack.add(value);
             }
 
-            const keys = this.getKeys(targetType, value);
+            const keys = this.getKeys((targetType as Function), value);
             let newValue: any = source ? source : {};
             if (!source && (this.transformationType === TransformationType.PLAIN_TO_CLASS || this.transformationType === TransformationType.CLASS_TO_CLASS)) {
                 if (isMap) {
@@ -103,16 +128,17 @@ export class TransformOperationExecutor {
                 let valueKey = key, newValueKey = key, propertyName = key;
                 if (!this.options.ignoreDecorators && targetType) {
                     if (this.transformationType === TransformationType.PLAIN_TO_CLASS) {
-                        const exposeMetadata = defaultMetadataStorage.findExposeMetadataByCustomName(targetType, key);
+                        const exposeMetadata = defaultMetadataStorage.findExposeMetadataByCustomName((targetType as Function), key);
                         if (exposeMetadata) {
                             propertyName = exposeMetadata.propertyName;
                             newValueKey = exposeMetadata.propertyName;
                         }
 
                     } else if (this.transformationType === TransformationType.CLASS_TO_PLAIN || this.transformationType === TransformationType.CLASS_TO_CLASS) {
-                        const exposeMetadata = defaultMetadataStorage.findExposeMetadata(targetType, key);
-                        if (exposeMetadata && exposeMetadata.options && exposeMetadata.options.name)
+                        const exposeMetadata = defaultMetadataStorage.findExposeMetadata((targetType as Function), key);
+                        if (exposeMetadata && exposeMetadata.options && exposeMetadata.options.name) {
                             newValueKey = exposeMetadata.options.name;
+                        }
                     }
                 }
 
@@ -132,10 +158,30 @@ export class TransformOperationExecutor {
                     type = targetType;
 
                 } else if (targetType) {
-                    const metadata = defaultMetadataStorage.findTypeMetadata(targetType, propertyName);
+
+                    const metadata = defaultMetadataStorage.findTypeMetadata((targetType as Function), propertyName);
                     if (metadata) {
-                        const options: TypeOptions = {newObject: newValue, object: value, property: propertyName};
-                        type = metadata.typeFunction(options);
+                        const options: TypeHelpOptions = { newObject: newValue, object: value, property: propertyName };
+                        const newType = metadata.typeFunction(options);
+                        if (metadata.options && metadata.options.discriminator && metadata.options.discriminator.property && metadata.options.discriminator.subTypes) {
+                            if (!(value[valueKey] instanceof Array)) {
+                                if (this.transformationType === TransformationType.PLAIN_TO_CLASS) {
+                                    type = metadata.options.discriminator.subTypes.find((subType) => subType.name === subValue[metadata.options.discriminator.property]);
+                                    type === undefined ? type = newType : type = type.value;
+                                    if (!metadata.options.keepDiscriminatorProperty) delete subValue[metadata.options.discriminator.property];
+                                }
+                                if (this.transformationType === TransformationType.CLASS_TO_CLASS) {
+                                    type = subValue.constructor;
+                                }
+                                if (this.transformationType === TransformationType.CLASS_TO_PLAIN) {
+                                    subValue[metadata.options.discriminator.property] = metadata.options.discriminator.subTypes.find((subType) => subType.value === subValue.constructor).name;
+                                }
+                            } else {
+                                type = metadata;
+                            }
+                        } else {
+                            type = newType;
+                        }
                         isSubValueMap = isSubValueMap || metadata.reflectedType === Map;
                     } else if (this.options.targetMaps) { // try to find a type in target maps
                         this.options.targetMaps
@@ -145,7 +191,8 @@ export class TransformOperationExecutor {
                 }
 
                 // if value is an array try to get its custom array type
-                const arrayType = value[valueKey] instanceof Array ? this.getReflectedType(targetType, propertyName) : undefined;
+                const arrayType = Array.isArray(value[valueKey]) ? this.getReflectedType((targetType as Function), propertyName) : undefined;
+
                 // const subValueKey = TransformationType === TransformationType.PLAIN_TO_CLASS && newKeyName ? newKeyName : key;
                 const subSource = source ? source[valueKey] : undefined;
 
@@ -162,18 +209,32 @@ export class TransformOperationExecutor {
                         continue;
                 }
 
-                if (!this.options.enableCircularCheck || !this.isCircular(subValue, level)) {
+                if (!this.options.enableCircularCheck || !this.isCircular(subValue)) {
                     let transformKey = this.transformationType === TransformationType.PLAIN_TO_CLASS ? newValueKey : key;
-                    let finalValue = this.transform(subSource, subValue, type, arrayType, isSubValueMap, level + 1);
-                    finalValue = this.applyCustomTransformations(finalValue, targetType, transformKey, value, this.transformationType);
+                    let finalValue;
+
+                    if (this.transformationType === TransformationType.CLASS_TO_PLAIN) {
+                        // Get original value
+                        finalValue = value[transformKey];
+                        // Apply custom transformation
+                        finalValue = this.applyCustomTransformations(finalValue, (targetType as Function), transformKey, value, this.transformationType);
+                        // If nothing change, it means no custom transformation was applied, so use the subValue.
+                        finalValue = (value[transformKey] === finalValue) ? subValue : finalValue;
+                        // Apply the default transformation
+                        finalValue = this.transform(subSource, finalValue, type, arrayType, isSubValueMap, level + 1);
+                    } else {
+                        finalValue = this.transform(subSource, subValue, type, arrayType, isSubValueMap, level + 1);
+                        finalValue = this.applyCustomTransformations(finalValue, (targetType as Function), transformKey, value, this.transformationType);
+                    }
+
                     if (newValue instanceof Map) {
                         newValue.set(newValueKey, finalValue);
                     } else {
                         newValue[newValueKey] = finalValue;
                     }
                 } else if (this.transformationType === TransformationType.CLASS_TO_CLASS) {
                     let finalValue = subValue;
-                    finalValue = this.applyCustomTransformations(finalValue, targetType, key, value, this.transformationType);
+                    finalValue = this.applyCustomTransformations(finalValue, (targetType as Function), key, value, this.transformationType);
                     if (newValue instanceof Map) {
                         newValue.set(newValueKey, finalValue);
                     } else {
@@ -182,6 +243,11 @@ export class TransformOperationExecutor {
                 }
 
             }
+
+            if (this.options.enableCircularCheck) {
+                this.recursionStack.delete(value);
+            }
+
             return newValue;
 
         } else {
@@ -224,9 +290,8 @@ export class TransformOperationExecutor {
     }
 
     // preventing circular references
-    private isCircular(object: Object, level: number) {
-        const transformed = this.transformedTypesMap.get(object);
-        return transformed !== undefined && transformed.level < level;
+    private isCircular(object: Object) {
+        return this.recursionStack.has(object);
     }
 
     private getReflectedType(target: Function, propertyName: string) {