1 |
|
2 | # Valida
|
3 | Valida - A lightweight sanitizer and validator library for Node.js.
|
4 |
|
5 | This document describes how Valida library works and which features it offers. Each section of this document includes usage examples. You can find additional examples at [examples](https://github.com/esnunes/valida/tree/master/examples) folder.
|
6 |
|
7 | ## Simple example
|
8 | ```javascript
|
9 | var schema = {
|
10 | id: [
|
11 | { sanitizer: Valida.Sanitizer.toInt },
|
12 | { validator: Valida.Validator.required }
|
13 | ],
|
14 | age: [
|
15 | { sanitizer: Valida.Sanitizer.toInt },
|
16 | { validator: Valida.Validator.required, groups: ['create'] }
|
17 | ],
|
18 | name: [
|
19 | { validator: Valida.Validator.required, groups: ['update'] }
|
20 | ],
|
21 | answers: [
|
22 | { validator: Valida.Validator.array },
|
23 | { validator: Valida.Validator.len, min: 3, max: 10 },
|
24 | ]
|
25 | };
|
26 |
|
27 | var person = { age: '10', answers: ['A', 'D'] };
|
28 |
|
29 | Valida.process(person, schema, function(err, ctx) {
|
30 | if (err) return console.log(err);
|
31 | if (!ctx.isValid()) return console.log(ctx.errors());
|
32 | console.log('valid', person);
|
33 | }, ['create']);
|
34 | ```
|
35 |
|
36 | ## Features
|
37 | - Sanitization
|
38 | - Synchronous and asynchronous validation
|
39 | - Groups
|
40 | - Extensible
|
41 |
|
42 | All the features are applied through the `process` function.
|
43 |
|
44 | ```js
|
45 | Valida.process(
|
46 | @data,
|
47 | @schema,
|
48 | @callback,
|
49 | @group
|
50 | );
|
51 | ```
|
52 | **options:**
|
53 |
|
54 | * `@data` is the object to be applied the sanitization and validation
|
55 | * `@schema` is an object describing to Valida how to process it
|
56 | * `@callback` is a function that is going to be called after processing the data
|
57 | * `@group` is a string or array describing which groups must be applied in this process (optional)
|
58 |
|
59 |
|
60 | ### Sanitization
|
61 |
|
62 | Valida supports synchronous sanitization.
|
63 |
|
64 | * `toInt`
|
65 | * `toFloat`
|
66 | * `toDate`
|
67 | * `trim`
|
68 |
|
69 | #### toInt
|
70 |
|
71 | **options:**
|
72 |
|
73 | * `radix` (optional, default 10)
|
74 |
|
75 | ```js
|
76 | var schema = {
|
77 | age: [{ sanitizer: Valida.Sanitizer.toInt }]
|
78 | };
|
79 | ```
|
80 |
|
81 | #### toFloat
|
82 |
|
83 | **options:**
|
84 |
|
85 | * `precision` (optional)
|
86 |
|
87 | ```js
|
88 | var schema = {
|
89 | salary: [{ sanitizer: Valida.Sanitizer.toFloat }]
|
90 | };
|
91 | ```
|
92 |
|
93 | #### toDate
|
94 |
|
95 | ```js
|
96 | var schema = {
|
97 | birthday: [{ sanitizer: Valida.Sanitizer.toDate }]
|
98 | };
|
99 | ```
|
100 |
|
101 | #### trim
|
102 |
|
103 | **options:**
|
104 |
|
105 | * `chars` (optional)
|
106 |
|
107 | ```js
|
108 |
|
109 | var schema = {
|
110 | name: [{ sanitizer: Valida.Sanitizer.trim }]
|
111 | };
|
112 | ```
|
113 |
|
114 | ### Validation
|
115 |
|
116 | Valida supports both synchronous and asynchronous validation.
|
117 |
|
118 | * `required`
|
119 | * `empty`
|
120 | * `regex`
|
121 | * `len`
|
122 | * `array`
|
123 | * `plainObject`
|
124 | * `date`
|
125 |
|
126 | #### required
|
127 |
|
128 | Field is required.
|
129 |
|
130 | ```js
|
131 | var schema = {
|
132 | age: [{ validator: Valida.Validator.required }]
|
133 | };
|
134 | ```
|
135 |
|
136 | #### empty
|
137 |
|
138 | Field must be empty.
|
139 |
|
140 | ```js
|
141 | var schema = {
|
142 | description: [{ validator: Valida.Validator.empty }]
|
143 | };
|
144 | ```
|
145 |
|
146 | #### regex
|
147 |
|
148 | Validation based in a regex.
|
149 |
|
150 | **options:**
|
151 |
|
152 | * `pattern`: regex pattern
|
153 | * `modifiers`: regex modifier (optional)
|
154 |
|
155 | ```js
|
156 | var schema = {
|
157 | name: [{ validator: Valida.Validator.regex, pattern: '[A-Z]', modifiers: 'i' }]
|
158 | };
|
159 | ```
|
160 |
|
161 | #### len
|
162 |
|
163 | Validation based in the size of an array.
|
164 |
|
165 | **options:**
|
166 |
|
167 | * `min`
|
168 | * `max`
|
169 |
|
170 | ```js
|
171 | var schema = {
|
172 | products: [{ validator: Valida.Validator.len, min: 2, max: 10 }]
|
173 | };
|
174 | ```
|
175 |
|
176 | #### array
|
177 |
|
178 | Field must be an array.
|
179 |
|
180 | ```js
|
181 | var schema = {
|
182 | products: [{ validator: Valida.Validator.array }]
|
183 | };
|
184 | ```
|
185 |
|
186 | #### plainObject
|
187 |
|
188 | Field must be a plain object.
|
189 |
|
190 | ```js
|
191 | var schema = {
|
192 | person: [{ validator: Valida.Validator.plainObject }]
|
193 | };
|
194 | ```
|
195 |
|
196 | #### date
|
197 |
|
198 | Field must be a date.
|
199 |
|
200 | ```js
|
201 | var schema = {
|
202 | createdAt: [{ validator: Valida.Validator.date }]
|
203 | };
|
204 | ```
|
205 |
|
206 | #### integer
|
207 |
|
208 | Field must be a integer.
|
209 |
|
210 | ```js
|
211 | var schema = {
|
212 | createdAt: [{ validator: Valida.Validator.integer }]
|
213 | };
|
214 | ```
|
215 |
|
216 | ### Groups
|
217 |
|
218 | Allows reuse the same schema validation for multiple actions. For example on creating an item a specific field is required. But on updating it that field is optional.
|
219 |
|
220 | ```js
|
221 | var schema = {
|
222 | id: [{ validator: Valida.Validator.required, groups: ['update'] }]
|
223 | products: [{ validator: Valida.Validator.array, groups: ['create'] }]
|
224 | };
|
225 |
|
226 | Valida.process(data, schema, function(err, ctx) {
|
227 | console.log('create', create);
|
228 | }, 'create');
|
229 | ```
|
230 |
|
231 | ### Extensible
|
232 |
|
233 | ## Contributors
|
234 | Would you like to contribute to this library? Don't be shy! [Contact me](mailto:esnunes@gmail.com) if you are interested on it.
|
235 |
|
236 | ## LICENSE
|
237 |
|
238 | (MIT License)
|
239 |
|
240 | Copyright (c) 2013 Eduardo Nunes <esnunes@gmail.com>
|
241 |
|
242 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
243 | of this software and associated documentation files (the "Software"), to deal
|
244 | in the Software without restriction, including without limitation the rights
|
245 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
246 | copies of the Software, and to permit persons to whom the Software is
|
247 | furnished to do so, subject to the following conditions:
|
248 |
|
249 | The above copyright notice and this permission notice shall be included in
|
250 | all copies or substantial portions of the Software.
|
251 |
|
252 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
253 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
254 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
255 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
256 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
257 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
258 | THE SOFTWARE.
|