1 | [![Build Status](https://travis-ci.org/BlueT/obj-filter.svg?branch=master)](https://travis-ci.org/BlueT/obj-filter)
|
2 | [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=obj-filter&metric=alert_status)](https://sonarcloud.io/dashboard?id=obj-filter)
|
3 |
|
4 | # obj-filter - JavaScript Object Filter.
|
5 |
|
6 | JavaScript Object Filter. **Deep** filtering key/content *recursively*.
|
7 | Support **wildcard**, **nested**, and **filter_function** in *template*.
|
8 |
|
9 | ## SYNOPSIS
|
10 |
|
11 | ~~~~ js
|
12 | "use strict";
|
13 |
|
14 | var filter = require('obj-filter');
|
15 |
|
16 | var template = {
|
17 | "runtime": {
|
18 | "connectionState": undefined,
|
19 | "powerState": function (args) {return "HELLOWORLD " + args},
|
20 | "bootTime": "my boot time",
|
21 | "paused": false,
|
22 | "snapshotInBackground": 1111111
|
23 | }
|
24 | };
|
25 |
|
26 | var clean_data = filter( template, fetchData() );
|
27 |
|
28 | var updated_data = filter.merge( clean_data, newUpdates() );
|
29 | ~~~~
|
30 |
|
31 | ## Template Object
|
32 | According to the **Template Object structure**, `obj-filter` supports the following types of value with different behaviour to build the result object.
|
33 |
|
34 | ### undefined
|
35 | If the *value* of the key is `undefined`, the key will be **filtered** (skipped) and will not included in result object.
|
36 |
|
37 | ### object
|
38 | If the *value* of the key is an `object`, `obj-filter` will _dive into it and check the **deeper** level of keys_.
|
39 |
|
40 | ### function
|
41 | If the *value* of the key is an `function`, `obj-filter` will _pass the **value** of the same key in **input data** to the **function**_, and includes it's returned data in result.
|
42 | So it's your call to customize how you would like to handle, define what you want to do with the input data. Be sure to **return something** from your function.
|
43 |
|
44 | - If return `undefined`, the key will be **filtered** (skipped).
|
45 | - If return anything else, the key will be **included**.
|
46 |
|
47 | ### Anything else (string, integer, `true`, `false`, etc)
|
48 | The value of the key will be **included**.
|
49 |
|
50 | ## Default Function
|
51 |
|
52 | ### Keep only wanted data
|
53 |
|
54 | When fetching data through API, sometimes the returned data could be Huge. You need many of them, but there are also too many trash included in returned data.
|
55 | Copying with `result[xxx] = input[xxx];` each by each, line by line, is a hell.
|
56 | Now you can copy one returned data structure (in JSON) to your favorite text editor, delete all unwanted lines, paste it back to your code, and use it as template.
|
57 |
|
58 | ~~~~ js
|
59 | "use strict";
|
60 |
|
61 | var filter = require('obj-filter');
|
62 |
|
63 | var template = {
|
64 | "runtime": {
|
65 | "connectionState": undefined, // In Template, when the value is undefined, the key will be ignored.
|
66 | "powerState": function (args) {return "HELLOWORLD " + args}, // pass data into your function, and use it as result value
|
67 | "bootTime": "my boot time", // The string is just for your own note. Will keep whatever input is in result.
|
68 | "paused": false, // Will keep whatever input is in result.
|
69 | "snapshotInBackground": 1111111 // Will keep whatever input is in result.
|
70 | }
|
71 | };
|
72 |
|
73 | var data = function_or_somewhere();
|
74 |
|
75 | // Assume:
|
76 | // var data = {
|
77 | // "vm": {
|
78 | // "type": "VirtualMachine"
|
79 | // },
|
80 | // "runtime": {
|
81 | // "device": 9999,
|
82 | // "connectionState": "connected",
|
83 | // "powerState": "poweredOn",
|
84 | // "bootTime": "2017-04-20T13:56:19.377Z",
|
85 | // "paused": false,
|
86 | // "snapshotInBackground": true
|
87 | // }
|
88 | //};
|
89 |
|
90 |
|
91 | var clean_data = filter(template, data);
|
92 |
|
93 | // clean_data is:
|
94 | {
|
95 | "runtime": {
|
96 | "powerState": "HELLOWORLD poweredOn",
|
97 | "bootTime": "2017-04-20T13:56:19.377Z",
|
98 | "paused": false,
|
99 | "snapshotInBackground": true
|
100 | }
|
101 | };
|
102 | ~~~~
|
103 |
|
104 | ### User Data Checks
|
105 |
|
106 | Validate user input data in browser (before send to server), or check them at server-side.
|
107 |
|
108 | ~~~~ js
|
109 | var template = {
|
110 | email: validateEmail(email), // call function validateEmail and use it's return value as value
|
111 | username: function (username) {
|
112 | if (/^[a-zA-Z_]+$/.test(username)) { // check if username contains only a-z or underscore
|
113 | return username;
|
114 | } else {
|
115 | throw new Error('Invalid username');
|
116 | }
|
117 | },
|
118 | password: "original password" // keep whatever user inputs
|
119 | }
|
120 |
|
121 | save_or_send( filter(template, inputData) );
|
122 | ~~~~
|
123 |
|
124 | ### Seperated template file
|
125 |
|
126 | You can save template into seperated files.
|
127 |
|
128 | Say _data_template/vmInfo.js_
|
129 |
|
130 | ~~~~ js
|
131 | {
|
132 | "runtime": {
|
133 | "connectionState": undefined,
|
134 | "powerState": function (args) {return "HELLOWORLD " + args},
|
135 | "bootTime": "my boot time",
|
136 | "paused": false,
|
137 | "snapshotInBackground": 1111111
|
138 | }
|
139 | };
|
140 | ~~~~
|
141 |
|
142 | Require it as template
|
143 |
|
144 | ~~~~ js
|
145 | var vm_tpl = require('data_template/vmInfo.js');
|
146 |
|
147 | var vmData = filter(vm_tpl, yourData)
|
148 | ~~~~
|
149 |
|
150 | ## `merge` Function
|
151 |
|
152 | ### Keep template keys when not provided in input data.
|
153 |
|
154 | ~~~~ js
|
155 | "use strict";
|
156 |
|
157 | var filter = require('obj-filter');
|
158 |
|
159 | var template = {
|
160 | "runtime": {
|
161 | "connectionState": undefined,
|
162 | "powerState": function (args) {return "HELLOWORLD " + args},
|
163 | "CoffeeTeaOrMe": "Me"
|
164 | }
|
165 | };;
|
166 |
|
167 | var newUpdates = fetchChanges();
|
168 |
|
169 | // Assume:
|
170 | // var data = {
|
171 | // "runtime": {
|
172 | // "connectionState": "connected",
|
173 | // "powerState": "poweredOn"
|
174 | // }
|
175 | //};
|
176 |
|
177 |
|
178 | var updated_data = filter.merge(template, newUpdates);
|
179 |
|
180 | // clean_data is:
|
181 | {
|
182 | "runtime": {
|
183 | "powerState": "HELLOWORLD poweredOn",
|
184 | "bootTime": "2017-04-20T13:56:19.377Z",
|
185 | "CoffeeTeaOrMe": "Me"
|
186 | }
|
187 | };
|
188 | ~~~~
|
189 |
|
190 | ## Contribute
|
191 | PRs welcome!
|
192 | If you use/like this module, please don't hesitate to give me a **Star**. I'll be happy whole day!
|
193 |
|
194 | _Hope this module can save your time, a tree, and a kitten._
|