Skip to content

Commit 9211a0b

Browse files
ThroyerThroyer
authored
Merge pull request #2 from Throyer/docs
Docs
2 parents f5f58ad + c6d1078 commit 9211a0b

File tree

6 files changed

+275
-161
lines changed

6 files changed

+275
-161
lines changed

‎README.md‎

Lines changed: 228 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,276 @@
11
# Entity diff
22

3-
Entity diff generator.
3+
A simple entity diff generator.
44

5-
How to use:
5+
generates a list of changes made to the entity.
6+
7+
All you need are two objects, one with the entity before the changes and the other with it after the changes.
8+
9+
<a target="_blank" href="https://stackblitz.com/edit/typescript-3heozh?file=index.ts">Try it out</a>
10+
11+
## how to Install
12+
13+
npm:
14+
```shell
15+
npm install entity-diff
16+
```
17+
18+
yarn:
19+
```shell
20+
yarn add entity-diff
21+
```
22+
23+
24+
*****
25+
26+
27+
## How to use:
628
``` typescript
729

830
import { Audit } from "entity-diff";
931

1032
const audit = new Audit();
1133

1234
const before = {
13-
name: "Lucas Oliveira",
35+
name: "Mason",
1436
age: 20
15-
}
37+
};
1638

1739
const after = {
18-
name: "Lucas",
40+
name: "Mason Floyd",
1941
age: 20
20-
}
42+
};
2143

2244
const result = audit.diff(before, after);
2345

2446
// result:
2547
// [
2648
// {
2749
// key: "name",
28-
// from: "Lucas Oliveira",
29-
// to: "Lucas"
50+
// from: "Mason",
51+
// to: "Mason Floyd"
3052
// }
3153
// ]
3254

3355
```
3456

57+
*****
3558

36-
Audit Options:
37-
``` typescript
59+
# Audit Options:
3860

39-
import { Audit } from "entity-diff";
61+
It is possible to change some information in the final result of the diffs using parameters.
4062

41-
const audit = new Audit(
42-
["id"], // ignore: list with ignored properties (optional)
63+
### Ignoring properties
4364

44-
[ // options: custom diff options for especific properties (optional)
45-
{
46-
key: // key name (required)
47-
title: // name displayed in diff (optional)
48-
customFormater: // function to customize the rendering of the `from` and `to` (optional)
65+
It is possible to ignore some keys of the objects audited through a list.
4966

50-
arrayOptions: { // arrayOptions: diff array options (optional)
51-
key: // used to search for the object in the other array (required)
52-
name: // property with the name displayed in the diff (optional)
53-
}
54-
}
55-
]
56-
);
67+
```typescript
68+
import { Audit } from "entity-diff";
5769

58-
const before = {
59-
id: 1,
60-
nome: "Fulano da silva",
61-
empresa: {
62-
id: 1,
63-
nome: "Algum lugar",
64-
cnpj: "12345678910"
65-
},
66-
permissoes: [
67-
{
68-
id: 1,
69-
nome: "ADMINISTRADOR"
70-
},
71-
{
72-
id: 2,
73-
nome: "USUARIO"
74-
}
75-
]
76-
};
70+
const before = {
71+
name: "Mason",
72+
age: 20
73+
};
7774

78-
const after = {
79-
id: 1,
80-
nome: "Fulano",
81-
empresa: {
82-
id: 2,
83-
nome: "Outro lugar",
84-
cnpj: "10987654321"
85-
},
86-
permissoes: [
87-
{
88-
id: 1,
89-
nome: "SUPER_USER"
90-
},
75+
const after = {
76+
name: "Mason Floyd", // this change will be ignored
77+
age: 25
78+
};
79+
80+
const ignore = ["name"];
81+
82+
const audit = new Audit({ ignore });
83+
84+
const result = audit.diff(before, after);
85+
86+
// result:
87+
// [
88+
// {
89+
// key: "age",
90+
// from: 20,
91+
// to: 25
92+
// }
93+
// ]
94+
```
95+
96+
### Different name in the keys
97+
98+
Changing the name that appears in the key in the result
99+
100+
```typescript
101+
import { Audit } from "entity-diff";
102+
103+
const before = {
104+
name: "Mason",
105+
age: 20
106+
};
107+
108+
const after = {
109+
name: "Mason Floyd",
110+
age: 25
111+
};
112+
113+
const options = [{ key: "name", title: "Person name" }];
114+
115+
const audit = new Audit({ options });
116+
117+
const result = audit.diff(before, after);
118+
119+
// result:
120+
// [
121+
// {
122+
// key: "Person name", // title defined in options
123+
// from: "Mason",
124+
// to: "Mason Floyd"
125+
// }
126+
// ]
127+
```
128+
129+
130+
### formatting the values displayed in "from" and "to"
131+
132+
It can be done through a function defined in options
133+
134+
```typescript
135+
import { format } from 'date-fns'
136+
import { Audit } from "entity-diff";
137+
138+
const before = {
139+
name: "Mason",
140+
age: 20
141+
};
142+
143+
const after = {
144+
name: "Mason Floyd",
145+
age: 20,
146+
updatedAt: "2020-09-08T18:04:56.627Z"
147+
};
148+
149+
const options = [
91150
{
92-
id: 4,
93-
nome: "PROGRAMADOR"
151+
key: "updatedAt",
152+
customFormatter: date => format(new Date(date), "MM/dd/yyyy")
94153
}
95-
]
96-
};
154+
];
97155

98-
const diffs = audit.diff(before, after);
156+
const audit = new Audit({ options });
157+
158+
const result = audit.diff(before, after);
159+
160+
// result:
161+
// [
162+
// {
163+
// key: "updatedAt",
164+
// from: null,
165+
// to: "09/08/2020"
166+
// }
167+
// ]
99168
```
100169

101-
**diffs**
102-
103-
``` json
104-
[
105-
{
106-
"key": "nome",
107-
"from": "Fulano da silva",
108-
"to": "Fulano"
109-
},
110-
{
111-
"key": "empresa",
112-
"type": "EDITADO",
113-
"details": [
170+
## Working with `array` diffs
171+
172+
when working with arrays, diffs are generated only when there is some value in `"arrayOptions"`.
173+
174+
The `"key"` property represents the key used to find the entities within the other array. it is optional, but by default entity-diff looks for the `"id"` key.
175+
176+
```typescript
177+
import { Audit } from "entity-diff";
178+
179+
const before = {
180+
name: "Mason",
181+
age: 20,
182+
roles: [
114183
{
115-
"key": "nome",
116-
"from": "Algum lugar",
117-
"to": "Outro lugar"
184+
id: 1,
185+
name: "ADM"
118186
},
119187
{
120-
"key": "cnpj",
121-
"from": "12345678910",
122-
"to": "10987654321"
188+
id: 2,
189+
name: "USER"
123190
}
124191
]
125-
},
126-
{
127-
"key": "permissoes",
128-
"type": "LISTA",
129-
"details": [
130-
{
131-
"key": "ADMINISTRADOR",
132-
"type": "EDITADO",
133-
"details": [
134-
{
135-
"key": "nome",
136-
"from": "ADMINISTRADOR",
137-
"to": "SUPER_USER"
138-
}
139-
]
140-
},
192+
};
193+
194+
const after = {
195+
name: "Mason",
196+
age: 20,
197+
roles: [
141198
{
142-
"key": "PROGRAMADOR",
143-
"type": "NOVO",
144-
"details": [
145-
{
146-
"key": "nome",
147-
"from": null,
148-
"to": "PROGRAMADOR"
149-
}
150-
]
199+
id: 1,
200+
name: "SUPER_USER"
151201
},
152202
{
153-
"key": "USUARIO",
154-
"type": "REMOVIDO",
155-
"details": [
156-
{
157-
"key": "nome",
158-
"from": "USUARIO",
159-
"to": null
160-
}
161-
]
162-
},
203+
id: 3,
204+
name: "TEC"
205+
}
163206
]
164-
}
165-
]
207+
};
208+
209+
const options = [
210+
{
211+
key: "roles",
212+
arrayOptions: {
213+
name: "name"
214+
}
215+
}
216+
];
217+
218+
const audit = new Audit({ options });
219+
220+
const result = audit.diff(before, after);
221+
222+
// resut:
223+
// [
224+
// {
225+
// "key": "roles",
226+
// "type": "ARRAY",
227+
// "details": [
228+
// {
229+
// "key": "ADM",
230+
// "type": "MODIFIED",
231+
// "details": [
232+
// {
233+
// "key": "name",
234+
// "from": "ADM",
235+
// "to": "SUPER_USER"
236+
// }
237+
// ]
238+
// },
239+
// {
240+
// "key": "TEC",
241+
// "type": "NEW",
242+
// "details": [
243+
// {
244+
// "key": "id",
245+
// "from": null,
246+
// "to": 3
247+
// },
248+
// {
249+
// "key": "name",
250+
// "from": null,
251+
// "to": "TEC"
252+
// }
253+
// ]
254+
// },
255+
// {
256+
// "key": "USER",
257+
// "type": "REMOVED",
258+
// "details": [
259+
// {
260+
// "key": "id",
261+
// "from": 2,
262+
// "to": null
263+
// },
264+
// {
265+
// "key": "name",
266+
// "from": "USER",
267+
// "to": null
268+
// }
269+
// ]
270+
// }
271+
// ]
272+
// }
273+
// ]
166274
```
275+
276+

0 commit comments

Comments
 (0)