class-transformer

class-transformer

Its ES6 and Typescript era. Nowadays you are working with classes and constructor objects more than ever. Class-transformer allows you to transform plain object to some instance of class and versa. Also it allows to serialize / deserialize object based on criteria. This tool is super useful on both frontend and backend.

Example how to use with angular 2 in plunker. Source code is available here.

Table of contents

• What is class-transformer
• Installation
  • Node.js
  • Browser
• Methods
  • plainToInstance
  • plainToClassFromExist
  • instanceToPlain
  • instanceToInstance
  • serialize
  • deserialize and deserializeArray
• Enforcing type-safe instance
• Working with nested objects
  • Providing more than one type option
• Exposing getters and method return values
• Exposing properties with different names
• Skipping specific properties
• Skipping depend of operation
• Skipping all properties of the class
• Skipping private properties, or some prefixed properties
• Using groups to control excluded properties
• Using versioning to control exposed and excluded properties
• Сonverting date strings into Date objects
• Working with arrays
• Additional data transformation
  • Basic usage
  • Advanced usage
• Other decorators
• Working with generics
• Implicit type conversion
• How does it handle circular references?
• Example with Angular2
• Samples
• Release notes

What is class-transformer⬆

In JavaScript there are two types of objects:

• plain (literal) objects
• class (constructor) objects

Plain objects are objects that are instances of Object class. Sometimes they are called literal objects, when created via {} notation. Class objects are instances of classes with own defined constructor, properties and methods. Usually you define them via class notation.

So, what is the problem?

Sometimes you want to transform plain javascript object to the ES6 classes you have. For example, if you are loading a json from your backend, some api or from a json file, and after you JSON.parse it you have a plain javascript object, not instance of class you have.

For example you have a list of users in your users.json that you are loading:

[
  {
    "id": 1,
    "firstName": "Johny",
    "lastName": "Cage",
    "age": 27
  },
  {
    "id": 2,
    "firstName": "Ismoil",
    "lastName": "Somoni",
    "age": 50
  },
  {
    "id": 3,
    "firstName": "Luke",
    "lastName": "Dacascos",
    "age": 12
  }
]

And you have a User class:

export class User {
  id: number;
  firstName: string;
  lastName: string;
  age: number;

  getName() {
    return this.firstName + ' ' + this.lastName;
  }

  isAdult() {
    return this.age > 36 && this.age < 60;
  }
}

You are assuming that you are downloading users of type User from users.json file and may want to write following code:

fetch('users.json').then((users: User[]) => {
  // you can use users here, and type hinting also will be available to you,
  //  but users are not actually instances of User class
  // this means that you can't use methods of User class
});

In this code you can use users[0].id, you can also use users[0].firstName and users[0].lastName. However you cannot use users[0].getName() or users[0].isAdult() because "users" actually is array of plain javascript objects, not instances of User object. You actually lied to compiler when you said that its users: User[].

So what to do? How to make a users array of instances of User objects instead of plain javascript objects? Solution is to create new instances of User object and manually copy all properties to new objects. But things may go wrong very fast once you have a more complex object hierarchy.

Alternatives? Yes, you can use class-transformer. Purpose of this library is to help you to map your plain javascript objects to the instances of classes you have.

This library also great for models exposed in your APIs, because it provides a great tooling to control what your models are exposing in your API. Here is an example how it will look like:

fetch('users.json').then((users: Object[]) => {
  const realUsers = plainToInstance(User, users);
  // now each user in realUsers is an instance of User class
});

Now you can use users[0].getName() and users[0].isAdult() methods.

Installation⬆

Node.js⬆

1. Install module:

   npm install class-transformer --save

2. reflect-metadata shim is required, install it too:

   npm install reflect-metadata --save

   and make sure to import it in a global place, like app.ts:

   import 'reflect-metadata';
   

3. ES6 features are used, if you are using old version of node.js you may need to install es6-shim:

   npm install es6-shim --save

   and import it in a global place like app.ts:

   import 'es6-shim';
   

Browser⬆

1. Install module:

   npm install class-transformer --save

2. reflect-metadata shim is required, install it too:

   npm install reflect-metadata --save

   add <script> to reflect-metadata in the head of your index.html:

   <html>
     <head>
       
       <script src="node_modules/reflect-metadata/Reflect.js"></script>
     </head>
     
   </html>
   

   If you are using angular 2 you should already have this shim installed.

3. If you are using system.js you may want to add this into map and package config:

   {
     "map": {
       "class-transformer": "node_modules/class-transformer"
     },
     "packages": {
       "class-transformer": { "main": "index.js", "defaultExtension": "js" }
     }
   }
   

Methods⬆

plainToInstance⬆

This method transforms a plain javascript object to instance of specific class.

import { plainToInstance } from 'class-transformer';

let users = plainToInstance(User, userJson); // to convert user plain object a single user. also supports arrays

plainToClassFromExist⬆

This method transforms a plain object into an instance using an already filled Object which is an instance of the target class.

const defaultUser = new User();
defaultUser.role = 'user';

let mixedUser = plainToClassFromExist(defaultUser, user); // mixed user should have the value role = user when no value is set otherwise.

instanceToPlain⬆

This method transforms your class object back to plain javascript object, that can be JSON.stringify later.

import { instanceToPlain } from 'class-transformer';
let photo = instanceToPlain(photo);

instanceToInstance⬆

This method transforms your class object into a new instance of the class object. This may be treated as deep clone of your objects.

import { instanceToInstance } from 'class-transformer';
let photo = instanceToInstance(photo);

You can also use an ignoreDecorators option in transformation options to ignore all decorators your classes are using.

serialize⬆

You can serialize your model right to json using serialize method:

import { serialize } from 'class-transformer';
let photo = serialize(photo);

serialize works with both arrays and non-arrays.

deserialize and deserializeArray⬆

You can deserialize your model from json using the deserialize method:

import { deserialize } from 'class-transformer';
let photo = deserialize(Photo, photo);

To make deserialization work with arrays, use the deserializeArray method:

import { deserializeArray } from 'class-transformer';
let photos = deserializeArray(Photo, photos);

Enforcing type-safe instance⬆

The default behaviour of the plainToInstance method is to set all properties from the plain object, even those which are not specified in the class.

import { plainToInstance } from 'class-transformer';

class User {
  id: number;
  firstName: string;
  lastName: string;
}

const fromPlainUser = {
  unkownProp: 'hello there',
  firstName: 'Umed',
  lastName: 'Khudoiberdiev',
};

console.log(plainToInstance(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 plainToInstance method while exposing all your class properties as a requirement.

import { Expose, plainToInstance } 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(plainToInstance(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, it's required to known what type of object you are trying to transform. Since Typescript does not have good reflection abilities yet, we should implicitly specify what type of object each property contain. This is done using @Type decorator.

Lets say we have an album with photos. And we are trying to convert album plain object to class object:

import { Type, plainToInstance } from 'class-transformer';

export class Album {
  id: number;

  name: string;

  @Type(() => Photo)
  photos: Photo[];
}

export class Photo {
  id: number;
  filename: string;
}

let album = plainToInstance(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 subtype name for the object and the possible subTypes that 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:

{
  "id": 1,
  "name": "foo",
  "topPhoto": {
    "id": 9,
    "filename": "cool_w