class-transformer
Advanced tools
Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors
The class-transformer package allows developers to transform plain object to class instances and vice versa. It also provides ways to serialize and deserialize object based on class definitions and handle custom transformations.
Plain to class transformation
Transforms a plain object to an instance of the class, allowing for easier manipulation and access to class methods.
import { plainToClass } from 'class-transformer';
class User {
id: number;
firstName: string;
lastName: string;
}
const plain = { id: 1, firstName: 'John', lastName: 'Doe' };
const userInstance = plainToClass(User, plain);Class to plain transformation
Transforms a class instance back into a plain object, which is useful for preparing objects for storage or transfer.
import { classToPlain } from 'class-transformer';
class User {
id: number;
firstName: string;
lastName: string;
}
const userInstance = new User();
userInstance.id = 1;
userInstance.firstName = 'John';
userInstance.lastName = 'Doe';
const plain = classToPlain(userInstance);Custom transformation
Allows for custom transformations using decorators to apply specific logic during the transformation process.
import { Transform, plainToClass } from 'class-transformer';
class User {
id: number;
@Transform(({ value }) => value.toUpperCase())
firstName: string;
}
const plain = { id: 1, firstName: 'John' };
const userInstance = plainToClass(User, plain);Serialization and deserialization
Provides methods to serialize a class instance to JSON and deserialize JSON back to a class instance.
import { serialize, deserialize, Deserialize } from 'class-transformer';
class User {
id: number;
firstName: string;
lastName: string;
}
const userInstance = new User();
userInstance.id = 1;
userInstance.firstName = 'John';
userInstance.lastName = 'Doe';
const json = serialize(userInstance);
const deserializedUser = deserialize(User, json);While class-validator is designed for validation of class instances, it is often used in conjunction with class-transformer. It does not provide transformation capabilities but offers a way to validate the properties of an object based on class decorators.
Joi is a powerful schema description language and data validator for JavaScript. Unlike class-transformer, Joi focuses on validation but does not offer class transformation features. It is often used for validating data structures, especially in API request validation.
Its ES6 and Typescript era. Nowadays you are working with classes and constructor objects more then 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 useful on both frontend and backend.
Install module:
npm install class-transformer --save
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";
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";
Install module:
npm install class-transformer --save
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.
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" }
}
}
In JavaScript there are two types of 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.
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[]) => {
// here 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 `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.
Alternatives? Yes, you can use this library. Purpose of this library is to help you to map you plain javascript objects to the instances of classes you have created.
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.
import {plainToClass} from "class-transformer";
let users = plainToClass(User, userJson); // to convert user plain object a single user. also supports arrays
This allows to map plain javascript array usersJson to array of User objects.
Now you can use users[0].getName() and users[0].isAdult() methods.
import {classToPlain} from "class-transformer";
let photo = classToPlain(photo);
This method transforms your class object back to plain javascript object, that can be JSON.stringify later.
import {classToClass} from "class-transformer";
let photo = classToClass(photo);
This method transforms your class object into new instance of the class object.
This maybe treated as deep clone of your objects.
You can also use a ignoreDecorators option in transformation options to ignore all decorators you classes is using.
You can serialize your model to right json using serialize method:
import {serialize} from "class-transformer";
let photo = serialize(photo);
serialize works with both arrays and non-arrays.
You can deserialize your model to from json using deserialize method:
import {deserialize} from "class-transformer";
let photo = deserialize(photo);
To make deserialization to work with arrays use deserializeArray method:
import {deserializeArray} from "class-transformer";
let photos = deserializeArray(photos);
When you are trying to transform objects that have nested objects,
its 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, plainToClass} from "class-transformer";
export class Album {
id: number;
name: string;
@Type(() => Photo)
photos: Photo[];
}
export class Photo {
id: number;
filename: string;
}
let album = plainToClass(Album, albumJson);
// now album is Album object with Photo objects inside
You can expose what you getter or method return by setting a @Expose() decorator to those getters or methods:
import {Expose} from "class-transformer";
export class User {
id: number;
firstName: string;
lastName: string;
password: string;
@Expose()
get name() {
return this.firstName + " " + this.lastName;
}
@Expose()
getFullName() {
return this.firstName + " " + this.lastName;
}
}
If you want to expose some of properties with different names,
you can do it by specifying a name option to @Expose decorator:
import {Expose} from "class-transformer";
export class User {
@Expose("uid")
id: number;
firstName: string;
lastName: string;
@Expose("secretKey")
password: string;
@Expose("fullName")
getFullName() {
return this.firstName + " " + this.lastName;
}
}
Sometimes you want to skip some properties during transformation.
This can be done using @Exclude decorator:
import {Exclude} from "class-transformer";
export class User {
id: number;
email: string;
@Exclude()
password: string;
}
Now when you transform a User, password property will be skipped and not be included in the transformed result.
You can control on what operation you will exclude a property. Use toClassOnly or toPlainOnly options:
import {Exclude} from "class-transformer";
export class User {
id: number;
email: string;
@Exclude({ toPlainOnly: true })
password: string;
}
Now password property will be excluded only during classToPlain operation. Oppositely, use toClassOnly option.
You can skip all properties of the class, and expose only those are needed explicitly:
import {Exclude, Expose} from "class-transformer";
@Exclude()
export class User {
@Expose()
id: number;
@Expose()
email: string;
password: string;
}
Now id and email will be exposed, and password will be excluded during transformation.
Alternatively, you can set exclusion strategy during transformation:
import {classToPlain} from "class-transformer";
let photo = classToPlain(photo, { strategy: "excludeAll" });
In this case you don't need to @Exclude() a whole class.
If you name your private properties with a prefix, lets say with _, then you can exclude such properties
from transformation too:
import {classToPlain} from "class-transformer";
let photo = classToPlain(photo, { excludePrefixes: ["_"] });
This will skip all properties that start with _ prefix.
You can pass any number of prefixes and all properties that begin with these prefixes will be ignored.
You can use groups to control what data will be exposed and what will not be:
import {Exclude, Expose} from "class-transformer";
@Exclude()
export class User {
id: number;
name: string;
@Expose({ groups: ["user", "admin"] }) // this means that this data will be exposed only to users and admins
email: string;
@Expose({ groups: ["user"] }) // this means that this data will be exposed only to users
password: string;
}
import {classToPlain} from "class-transformer";
let user1 = classToPlain(user, { groups: ["user"] }); // will contain id, name, email and password
let user2 = classToPlain(user, { groups: ["admin"] }); // will contain id, name and email
If you are building an API that has different versions, class-transformer has extremely useful tools for that. You can control which properties of your model should be exposed or excluded in what version. Example:
import {Exclude, Expose} from "class-transformer";
@Exclude()
export class User {
id: number;
name: string;
@Expose({ since: 0.7, until: 1 }) // this means that this property will be exposed for version starting from 0.7 until 1
email: string;
@Expose({ since: 2.1 }) // this means that this property will be exposed for version starting from 2.1
password: string;
}
import {classToPlain} from "class-transformer";
let user1 = classToPlain(user, { 0.5 }); // will contain id and name
let user2 = classToPlain(user, { 0.7 }); // will contain id, name and email
let user3 = classToPlain(user, { 1 }); // will contain id and name
let user4 = classToPlain(user, { 2 }); // will contain id and name
let user5 = classToPlain(user, { 2.1 }); // will contain id, name nad password
Sometimes you have a Date in your plain javascript object received in a string format.
And you want to create a real javascript Date object from it.
You can do it simply by passing a Date object to the @Type decorator:
import {Type} from "class-transformer";
export class User {
id: number;
email: string;
password: string;
@Type(() => Date)
registrationDate: Date;
}
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.
When you are using arrays you must provide a type of the object that array contains.
This type, you specify in a @Type() decorator:
import {ArrayType} from "class-transformer";
export class Photo {
id: number;
name: string;
@Type(() => Album)
albums: Album[];
}
You can also use custom array types:
import {ArrayType} from "class-transformer";
export class AlbumCollection extends Array<Album> {
// custom array functions ...
}
export class Photo {
id: number;
name: string;
@Type(() => Album)
albums: AlbumCollection;
}
Library will handle proper transformation automatically.
Circular references are ignored.
For example, if you are transforming class User that contains property photos with type of Photo,
and Photo contains link user to its parent User, then user will be ignored during transformation.
Circular references are not ignored only during classToClass operation.
Lets say you want to download users and want them automatically to be mapped to the instances of User class.
import {plainToClass} from "class-transformer";
this.http
.get("users.json")
.map(res => res.json())
.map(res => plainToClass(User, res))
.subscribe(users => {
// now "users" is type of User[] and each user have getName() and isAdult() methods available
console.log(users);
});
You can also inject a class ClassTransformer as a service in providers, and use its methods.
Take a look on samples in ./sample for more examples of usages.
See information about breaking changes and release notes here.
FAQs
Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors
The npm package class-transformer receives a total of 1,999,978 weekly downloads. As such, class-transformer popularity was classified as popular.
We found that class-transformer demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.