Merge branch 'master' into fix-overwrite-default-values

Author: NoNameProvided

CHANGELOG.md

@@ -1,94 +1,100 @@
 # Changelog and release notes
 
+### 0.2.1
+
+#### Added
+
+-   add option to strip unkown properties via using the `excludeExtraneousValues` option
+
 ### 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
+-   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
+-   fix bug when transforming `null` values as primitives
 
 ### 0.1.10
 
 #### Fixed
 
-- improve MetadataStorage perf by changing from Arrays to ES6 Maps by @sheiidan
-- fixed getAncestor issue with unknown nested properties by @247GradLabs
+-   improve MetadataStorage perf by changing from Arrays to ES6 Maps by @sheiidan
+-   fixed getAncestor issue with unknown nested properties by @247GradLabs
 
 ### 0.1.9
 
 #### Fixed
 
-- objects with `null` prototype are converted properly now
-- objects with unknown non primitive properties are converted properly now
-- corrected a typo in the README.md
-- fixed the deserialize example in the README.md
+-   objects with `null` prototype are converted properly now
+-   objects with unknown non primitive properties are converted properly now
+-   corrected a typo in the README.md
+-   fixed the deserialize example in the README.md
 
 ### 0.1.4
 
 #### Added
 
-- added `TransformClassToPlain` and `TransformClassToClass` decorators
+-   added `TransformClassToPlain` and `TransformClassToClass` decorators
 
 ### 0.1.0
 
 #### Added
 
-- renamed library from `constructor-utils` to `class-transformer`
-- completely renamed most of names
-- renamed all main methods: `plainToConstructor` now is `plainToClass` and `constructorToPlain` is `classToPlain`, etc.
-- `plainToConstructorArray` method removed - now `plainToClass` handles it
-- `@Skip()` decorator renamed to `@Exclude()`
-- added `@Expose` decorator
-- added lot of new options: groups, versioning, custom names, etc.
-- methods and getters that should be exposed must be decorated with `@Expose` decorator
-- added `excludedPrefix` to class transform options that allows exclude properties that start with one of the given prefix
+-   renamed library from `constructor-utils` to `class-transformer`
+-   completely renamed most of names
+-   renamed all main methods: `plainToConstructor` now is `plainToClass` and `constructorToPlain` is `classToPlain`, etc.
+-   `plainToConstructorArray` method removed - now `plainToClass` handles it
+-   `@Skip()` decorator renamed to `@Exclude()`
+-   added `@Expose` decorator
+-   added lot of new options: groups, versioning, custom names, etc.
+-   methods and getters that should be exposed must be decorated with `@Expose` decorator
+-   added `excludedPrefix` to class transform options that allows exclude properties that start with one of the given prefix
 
 ### 0.0.22
 
 #### Fixed
 
-- fixed array with primitive types being converted
+-   fixed array with primitive types being converted
 
 ### 0.0.18-0.0.21
 
 #### Fixed
 
-- fixed bugs when getters are not converted with es6 target
+-   fixed bugs when getters are not converted with es6 target
 
 ### 0.0.17
 
 #### Fixed
 
-- fixed issue #4
-- added type guessing during transformation from constructor to plain object
-- added sample with generics
+-   fixed issue #4
+-   added type guessing during transformation from constructor to plain object
+-   added sample with generics
 
 ### 0.0.16
 
 #### Changed
 
-- renamed `constructor-utils/constructor-utils` to `constructor-utils` package namespace
+-   renamed `constructor-utils/constructor-utils` to `constructor-utils` package namespace
 
 ### 0.0.15
 
 #### Removed
 
-- removed code mappings from package
+-   removed code mappings from package
 
 ### 0.0.14
 
 #### Removed
 
-- removed `import "reflect-metadata"` from source code. Now reflect metadata should be included like any other shims.
+-   removed `import "reflect-metadata"` from source code. Now reflect metadata should be included like any other shims.
 
 ### 0.0.13
 
 #### Changed
 
-- Library has changed its name from `serializer.ts` to `constructor-utils`.
-- Added `constructor-utils` namespace.
+-   Library has changed its name from `serializer.ts` to `constructor-utils`.
+-   Added `constructor-utils` namespace.

README.md

@@ -245,6 +245,62 @@ import {deserializeArray} from "class-transformer";
 let photos = deserializeArray(Photo, photos);
 ```
 
+## Enforcing type-safe instance
+
+The default behaviour of the `plainToClass` method is to set *all* properties from the plain object, 
+even those which are not specified in the class.
+
+```typescript
+import {plainToClass} from "class-transformer";
+
+class User {
+  id: number
+  firstName: string
+  lastName: string
+}
+
+const fromPlainUser = {
+  unkownProp: 'hello there',
+  firstName: 'Umed',
+  lastName: 'Khudoiberdiev',
+}
+
+console.log(plainToClass(User, fromPlainUser))
+
+// User {
+//   unkownProp: 'hello there',
+//   firstName: 'Umed',
+//   lastName: 'Khudoiberdiev',
+// }
+```
+
+If this behaviour does not suit your needs, you can use the `excludeExtraneousValues` option 
+in the `plainToClass` method while *exposing all your class properties* as a requirement.
+
+```typescript
+import {Expose, plainToClass} from "class-transformer";
+
+class User {
+    @Expose() id: number;
+    @Expose() firstName: string;
+    @Expose() lastName: string;
+}
+
+const fromPlainUser = {
+  unkownProp: 'hello there',
+  firstName: 'Umed',
+  lastName: 'Khudoiberdiev',
+}
+
+console.log(plainToClass(User, fromPlainUser, { excludeExtraneousValues: true }))
+
+// User {
+//   id: undefined,
+//   firstName: 'Umed',
+//   lastName: 'Khudoiberdiev' 
+// }
+```
+
 ## Working with nested objects
 
 When you are trying to transform objects that have nested objects,
@@ -805,4 +861,4 @@ usages.
 
 ## Release notes
 
-See information about breaking changes and release notes [here](https://github.com/pleerock/class-transformer/tree/master/doc/release-notes.md).
+See information about breaking changes and release notes [here](https://github.com/pleerock/class-transformer/tree/master/doc/release-notes.md).