Skip to content

Commit 6292d72

Browse files
author
Umed Khudoiberdiev
committed
updated readme and version bump
1 parent 67aba85 commit 6292d72

File tree

2 files changed

+144
-96
lines changed

2 files changed

+144
-96
lines changed

‎README.md

Lines changed: 143 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -13,72 +13,7 @@ Also it allows to serialize / deserialize object based on criteria.
1313
This tool is super useful on both frontend and backend.
1414

1515
Example how to use with angular 2 in [plunker](http://plnkr.co/edit/Mja1ZYAjVySWASMHVB9R).
16-
Source code is [here](https://github.com/pleerock/class-transformer-demo).
17-
18-
## Installation
19-
20-
### Node.js
21-
22-
1. Install module:
23-
24-
`npm install class-transformer --save`
25-
26-
2. `reflect-metadata` shim is required, install it too:
27-
28-
`npm install reflect-metadata --save`
29-
30-
and make sure to import it in a global place, like app.ts:
31-
32-
```typescript
33-
import "reflect-metadata";
34-
```
35-
36-
3. ES6 features are used, if you are using old version of node.js you may need to install es6-shim:
37-
38-
`npm install es6-shim --save`
39-
40-
and import it in a global place like app.ts:
41-
42-
```typescript
43-
import "es6-shim";
44-
```
45-
46-
### Browser
47-
48-
1. Install module:
49-
50-
`npm install class-transformer --save`
51-
52-
2. `reflect-metadata` shim is required, install it too:
53-
54-
`npm install reflect-metadata --save`
55-
56-
add `<script>` to reflect-metadata in the head of your `index.html`:
57-
58-
```html
59-
<html>
60-
<head>
61-
<!-- ... -->
62-
<script src="node_modules/reflect-metadata/Reflect.js"></script>
63-
</head>
64-
<!-- ... -->
65-
</html>
66-
```
67-
68-
If you are using angular 2 you should already have this shim installed.
69-
70-
3. If you are using system.js you may want to add this into `map` and `package` config:
71-
72-
```json
73-
{
74-
"map": {
75-
"class-transformer": "node_modules/class-transformer"
76-
},
77-
"packages": {
78-
"class-transformer": { "main": "index.js", "defaultExtension": "js" }
79-
}
80-
}
81-
```
16+
Source code is available [here](https://github.com/pleerock/class-transformer-demo).
8217

8318
## What is class-transformer
8419

@@ -95,8 +30,8 @@ Usually you define them via `class` notation.
9530
So, what is the problem?
9631

9732
Sometimes you want to transform plain javascript object to the ES6 **classes** you have.
98-
For example, if you are loading a json from your backend, some api or from a json file.
99-
After you `JSON.parse` it you have a plain javascript object, not instance of class you have.
33+
For example, if you are loading a json from your backend, some api or from a json file,
34+
and after you `JSON.parse` it you have a plain javascript object, not instance of class you have.
10035

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

@@ -144,58 +79,138 @@ following code:
14479

14580
```typescript
14681
fetch("users.json").then((users: User[]) => {
147-
// here you can use users[0].id, you can also use users[0].firstName and users[0].lastName
148-
// however you cannot use users[0].getName() or users[0].isAdult() because "users" actually is
149-
// array of plain javascript objects, not instances of User object.
150-
// You actually lied to compiler when you said that `users: User[]`.
82+
// you can use users here, and type hinting also will be available to you,
83+
// but users are not actually instances of User class
84+
// this means that you can't use methods of User class
15185
});
15286
```
15387

88+
In this code you can use `users[0].id`, you can also use `users[0].firstName` and `users[0].lastName`.
89+
However you cannot use `users[0].getName()` or `users[0].isAdult()` because "users" actually is
90+
array of plain javascript objects, not instances of User object.
91+
You actually lied to compiler when you said that its `users: User[]`.
92+
15493
So what to do? How to make a `users` array of instances of `User` objects instead of plain javascript objects?
15594
Solution is to create new instances of User object and manually copy all properties to new objects.
95+
But things may go wrong very fast once you have a more complex object hierarchy.
15696

157-
Alternatives? Yes, you can use this library. Purpose of this library is to help you to map you plain javascript
158-
objects to the instances of classes you have created.
97+
Alternatives? Yes, you can use class-transformer. Purpose of this library is to help you to map you plain javascript
98+
objects to the instances of classes you have.
15999

160100
This library also great for models exposed in your APIs,
161101
because it provides a great tooling to control what your models are exposing in your API.
102+
Here is example how it will look like:
103+
104+
```typescript
105+
fetch("users.json").then((users: Object[]) => {
106+
const realUsers = plainToClass(users);
107+
// now each user in realUsers is instance of User class
108+
});
109+
```
110+
111+
Now you can use `users[0].getName()` and `users[0].isAdult()` methods.
112+
113+
## Installation
114+
115+
### Node.js
116+
117+
1. Install module:
118+
119+
`npm install class-transformer --save`
120+
121+
2. `reflect-metadata` shim is required, install it too:
122+
123+
`npm install reflect-metadata --save`
124+
125+
and make sure to import it in a global place, like app.ts:
126+
127+
```typescript
128+
import "reflect-metadata";
129+
```
130+
131+
3. ES6 features are used, if you are using old version of node.js you may need to install es6-shim:
132+
133+
`npm install es6-shim --save`
134+
135+
and import it in a global place like app.ts:
136+
137+
```typescript
138+
import "es6-shim";
139+
```
140+
141+
### Browser
142+
143+
1. Install module:
144+
145+
`npm install class-transformer --save`
146+
147+
2. `reflect-metadata` shim is required, install it too:
148+
149+
`npm install reflect-metadata --save`
150+
151+
add `<script>` to reflect-metadata in the head of your `index.html`:
152+
153+
```html
154+
<html>
155+
<head>
156+
<!-- ... -->
157+
<script src="node_modules/reflect-metadata/Reflect.js"></script>
158+
</head>
159+
<!-- ... -->
160+
</html>
161+
```
162+
163+
If you are using angular 2 you should already have this shim installed.
164+
165+
3. If you are using system.js you may want to add this into `map` and `package` config:
166+
167+
```json
168+
{
169+
"map": {
170+
"class-transformer": "node_modules/class-transformer"
171+
},
172+
"packages": {
173+
"class-transformer": { "main": "index.js", "defaultExtension": "js" }
174+
}
175+
}
176+
```
162177

163178
### Methods
164179

165180
#### plainToClass
166181

182+
This method transforms a plain javascript object to instance of specific class.
183+
167184
```typescript
168185
import {plainToClass} from "class-transformer";
169186
170187
let users = plainToClass(User, userJson); // to convert user plain object a single user. also supports arrays
171188
```
172189

173-
This allows to map plain javascript array `usersJson` to array of `User` objects.
174-
Now you can use `users[0].getName()` and `users[0].isAdult()` methods.
175-
176190
#### classToPlain
177191

192+
This method transforms your class object back to plain javascript object, that can be `JSON.stringify` later.
193+
178194
```typescript
179195
import {classToPlain} from "class-transformer";
180196
let photo = classToPlain(photo);
181197
```
182198

183-
This method transforms your class object back to plain javascript object, that can be `JSON.stringify` later.
184-
185199
#### classToClass
186200

201+
This method transforms your class object into new instance of the class object.
202+
This maybe treated as deep clone of your objects.
203+
187204
```typescript
188205
import {classToClass} from "class-transformer";
189206
let photo = classToClass(photo);
190207
```
191208

192-
This method transforms your class object into new instance of the class object.
193-
This maybe treated as deep clone of your objects.
194209
You can also use a `ignoreDecorators` option in transformation options to ignore all decorators you classes is using.
195210

196211
#### serialize
197212

198-
You can serialize your model to right json using `serialize` method:
213+
You can serialize your model right to the json using `serialize` method:
199214

200215
```typescript
201216
import {serialize} from "class-transformer";
@@ -206,7 +221,7 @@ let photo = serialize(photo);
206221

207222
#### deserialize and deserializeArray
208223

209-
You can deserialize your model to from json using `deserialize` method:
224+
You can deserialize your model to from a json using `deserialize` method:
210225

211226
```typescript
212227
import {deserialize} from "class-transformer";
@@ -228,7 +243,8 @@ Since Typescript does not have good reflection abilities yet,
228243
we should implicitly specify what type of object each property contain.
229244
This is done using `@Type` decorator.
230245

231-
Lets say we have an album with photos. And we are trying to convert album plain object to class object:
246+
Lets say we have an album with photos.
247+
And we are trying to convert album plain object to class object:
232248

233249
```typescript
234250
import {Type, plainToClass} from "class-transformer";
@@ -254,7 +270,7 @@ let album = plainToClass(Album, albumJson);
254270

255271
### Exposing getters and method return values
256272

257-
You can expose what you getter or method return by setting a `@Expose()` decorator to those getters or methods:
273+
You can expose what your getter or method return by setting a `@Expose()` decorator to those getters or methods:
258274

259275
```typescript
260276
import {Expose} from "class-transformer";
@@ -280,7 +296,7 @@ export class User {
280296

281297
### Exposing properties with different names
282298

283-
If you want to expose some of properties with different names,
299+
If you want to expose some of properties with a different name,
284300
you can do it by specifying a `name` option to `@Expose` decorator:
285301

286302
```typescript
@@ -378,8 +394,8 @@ In this case you don't need to `@Exclude()` a whole class.
378394

379395
### Skipping private properties, or some prefixed properties
380396

381-
If you name your private properties with a prefix, lets say with `_`, then you can exclude such properties
382-
from transformation too:
397+
If you name your private properties with a prefix, lets say with `_`,
398+
then you can exclude such properties from transformation too:
383399

384400
```typescript
385401
import {classToPlain} from "class-transformer";
@@ -388,6 +404,39 @@ let photo = classToPlain(photo, { excludePrefixes: ["_"] });
388404

389405
This will skip all properties that start with `_` prefix.
390406
You can pass any number of prefixes and all properties that begin with these prefixes will be ignored.
407+
For example:
408+
409+
```typescript
410+
import {Expose} from "class-transformer";
411+
412+
export class User {
413+
414+
id: number;
415+
private _firstName: string;
416+
private _lastName: string;
417+
_password: string;
418+
419+
setName(firstName: string, lastName: string) {
420+
this._firstName = firstName;
421+
this._lastName = lastName;
422+
}
423+
424+
@Expose()
425+
get name() {
426+
return this.firstName + " " + this.lastName;
427+
}
428+
429+
}
430+
431+
const user = new User();
432+
user.id = 1;
433+
user.setName("Johny", "Cage");
434+
user._password = 123;
435+
436+
const plainUser = classToPlain(user, { excludePrefixes: ["_"] });
437+
// here plainUser will be equal to
438+
// { id: 1, name: "Johny Cage" }
439+
```
391440

392441
### Using groups to control excluded properties
393442

@@ -442,11 +491,11 @@ export class User {
442491

443492
```typescript
444493
import {classToPlain} from "class-transformer";
445-
let user1 = classToPlain(user, { 0.5 }); // will contain id and name
446-
let user2 = classToPlain(user, { 0.7 }); // will contain id, name and email
447-
let user3 = classToPlain(user, { 1 }); // will contain id and name
448-
let user4 = classToPlain(user, { 2 }); // will contain id and name
449-
let user5 = classToPlain(user, { 2.1 }); // will contain id, name nad password
494+
let user1 = classToPlain(user, { version: 0.5 }); // will contain id and name
495+
let user2 = classToPlain(user, { version: 0.7 }); // will contain id, name and email
496+
let user3 = classToPlain(user, { version: 1 }); // will contain id and name
497+
let user4 = classToPlain(user, { version: 2 }); // will contain id and name
498+
let user5 = classToPlain(user, { version: 2.1 }); // will contain id, name nad password
450499
```
451500

452501
### Сonverting date strings into Date objects
@@ -543,7 +592,7 @@ it will convert a date value in your photo object to moment date.
543592

544593
### Working with generics
545594

546-
Generics are not supported because TypeScript does not have good reflection abilities.
595+
Generics are not supported because TypeScript does not have good reflection abilities yet.
547596
Once TypeScript team provide us better runtime type reelection tools, generics will be implemented.
548597
There are some tweaks however you can use, that maybe can solve your problem.
549598
[Checkout this example.](https://github.com/pleerock/class-transformer/tree/master/sample/sample4-generics)
@@ -582,7 +631,6 @@ Source code is [here](https://github.com/pleerock/class-transformer-demo).
582631
Take a look on samples in [./sample](https://github.com/pleerock/class-transformer/tree/master/sample) for more examples of
583632
usages.
584633

585-
586634
## Release notes
587635

588636
See information about breaking changes and release notes [here](https://github.com/pleerock/class-transformer/tree/master/doc/release-notes.md).

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "class-transformer",
3-
"version": "0.1.0-beta.10",
3+
"version": "0.1.0",
44
"description": "Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors",
55
"license": "MIT",
66
"readmeFilename": "README.md",

0 commit comments

Comments
 (0)