merge: release 0.4.1 (#992)

Author: NoNameProvided

.eslintrc.yml

@@ -12,7 +12,6 @@ extends:
   - 'plugin:@typescript-eslint/recommended-requiring-type-checking'
   - 'plugin:jest/recommended'
   - 'prettier'
-  - 'prettier/@typescript-eslint'
 rules:
   '@typescript-eslint/explicit-member-accessibility': off
   '@typescript-eslint/no-angle-bracket-type-assertion': off

.gitbook.yaml

@@ -0,0 +1,4 @@
+root: ./docs
+​structure:  
+  readme: pages/01-getting-started.md  
+  summary: SUMMARY.md​

.github/workflows/auto-approve-dependabot-workflow.yml

@@ -1,6 +1,6 @@
 name: Dependabot auto-merge
 on:
-  pull_request
+  pull_request_target
 jobs:
   dependabot:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 _This changelog follows the [keep a changelog][keep-a-changelog]_ format to maintain a human readable changelog.
 
+### [0.4.1][v0.4.1] - 2021-11-20
+
+> **NOTE:** This version fixes a security vulnerability allowing denial of service attacks with a specially crafted request payload. Please update as soon as possible.
+
+#### Fixed
+
+- prevent unhandled error in `plaintToclass` when union-type member is undefined
+- fixed a scenario when a specially crafted JS object would be parsed to Array
+
+#### Changed
+
+- various dev-dependencies updated
+
 ### [0.4.0][v0.4.0] [BREAKING CHANGE] - 2021-02-14
 
 #### Breaking Changes
@@ -199,6 +212,7 @@ This version has introduced a breaking-change when this library is used with cla
 - Library has changed its name from `serializer.ts` to `constructor-utils`.
 - Added `constructor-utils` namespace.
 
+[v0.4.1]: https://github.com/typestack/class-transformer/compare/v0.4.0...v0.4.1
 [v0.4.0]: https://github.com/typestack/class-transformer/compare/v0.3.2...v0.4.0
 [v0.3.2]: https://github.com/typestack/class-transformer/compare/v0.3.1...v0.3.2
 [v0.3.1]: https://github.com/typestack/class-transformer/compare/v0.2.3...v0.3.1

README.md

@@ -676,8 +676,6 @@ export class User {
 }
 ```
 
-Note, that dates will be converted to strings when you'll try to convert class object to plain object.
-
 Same technique can be used with `Number`, `String`, `Boolean`
 primitive types when you want to convert your values into these types.
 

docs/SUMMARY.md

@@ -0,0 +1,4 @@
+# Table of contents
+
+- [Getting Started](pages/01-getting-started.md)
+- [Basic usage](pages/02-basis-usage.md)

docs/pages/01-getting-started.md

@@ -0,0 +1,74 @@
+# Getting Started
+
+The `class-transformer` package is a zero-dependency utility library helping you to quickly transform class instances to plain objects and vice-versa.
+It works well with the [`class-validator`][class-validator] library. The main features include:
+
+- conditionally transforming object properties
+- excluding specific properties from the transformed object
+- exposing properties under a different name on the transformed object
+- supports both NodeJS and browsers
+- fully three-shakable
+- zero external dependencies
+
+## Installation
+
+To start using class-transformer install the required packages via NPM:
+
+```bash
+npm install class-transformer reflect-metadata
+```
+
+Import the `reflect-metadata` package at the **first line** of your application:
+
+```ts
+import 'reflect-metadata';
+
+// Your other imports and initialization code
+// comes here after you imported the reflect-metadata package!
+```
+
+As the last step, you need to enable emitting decorator metadata in your Typescript config. Add these two lines to your `tsconfig.json` file under the `compilerOptions` key:
+
+```json
+"emitDecoratorMetadata": true,
+"experimentalDecorators": true,
+```
+
+Now you are ready to use class-transformer with Typescript!
+
+## Basic Usage
+
+The most basic usage is to transform a class to a plain object:
+
+```ts
+import { Expose, Exclude, classToPlain } from 'class-transformer';
+
+class User {
+  /**
+   * When transformed to plain the `_id` property will be remapped to `id`
+   * in the plain object.
+   */
+  @Expose({ name: 'id' })
+  private _id: string;
+
+  /**
+   * Expose the `name` property as it is in the plain object.
+   */
+  @Expose()
+  public name: string;
+
+  /**
+   * Exclude the `passwordHash` so it won't be included in the plain object.
+   */
+  @Exclude()
+  public passwordHash: string;
+}
+
+const user = getUserMagically();
+// contains: User { _id: '42', name: 'John Snow', passwordHash: '2f55ce082...' }
+
+const plain = classToPlain(user);
+// contains { id: '42', name: 'John Snow' }
+```
+
+[class-validator]: https://github.com/typestack/class-validator/

docs/pages/02-basic-usage.md

@@ -0,0 +1,20 @@
+# Basic usage
+
+There are two main exported functions what can be used for transformations:
+
+- `plainToClass` - transforms a plain object to an instance of the specified class constructor
+- `classToPlain` - transforms a _known_ class instance to a plain object
+
+Both function transforms the source object to the target via applying the metadata registered by the decorators on
+the class definition. The four main decorators are:
+
+- `@Expose` specifies how expose the given property on the plain object
+- `@Exclude` marks the property as skipped, so it won't show up in the transformation
+- `@Transform` allows specifying a custom transformation on the property via a custom handler
+- `@Type` decorator explicitly sets the type of the property, during the transformation `class-transformer` will attempt
+  to create an instance of the specified type
+
+You must always decorate all your properties with an `@Expose` or `@Exclude` decorator.
+
+> **NOTE:** It's important to remember `class-transformer` will call the target type with am empty constructor, so if
+> you are using a type what requires special setup, you need to use a `@Transform` decorator and create the instance yourself.