1 | # Valida
|
2 | [![Build Status](https://travis-ci.org/esnunes/valida.svg?branch=master)](https://travis-ci.org/esnunes/valida)
|
3 | [![npm version](https://badge.fury.io/js/valida.svg)](http://badge.fury.io/js/valida)
|
4 |
|
5 | Valida - A lightweight sanitizer and validator
|
6 | library for Node.js.
|
7 |
|
8 | 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.
|
9 |
|
10 | ## Simple example
|
11 | ```javascript
|
12 | var schema = {
|
13 | id: [
|
14 | { sanitizer: Valida.Sanitizer.toInt },
|
15 | { validator: Valida.Validator.required }
|
16 | ],
|
17 | age: [
|
18 | { sanitizer: Valida.Sanitizer.toInt },
|
19 | { validator: Valida.Validator.required, groups: ['create'] }
|
20 | ],
|
21 | name: [
|
22 | { validator: Valida.Validator.required, groups: ['update'] }
|
23 | ],
|
24 | answers: [
|
25 | { validator: Valida.Validator.array },
|
26 | { validator: Valida.Validator.len, min: 3, max: 10 },
|
27 | ]
|
28 | };
|
29 |
|
30 | var person = { age: '10', answers: ['A', 'D'] };
|
31 |
|
32 | Valida.process(person, schema, function(err, ctx) {
|
33 | if (err) return console.log(err);
|
34 | if (!ctx.isValid()) return console.log(ctx.errors());
|
35 | console.log('valid', person);
|
36 | }, ['create']);
|
37 | ```
|
38 |
|
39 | ## Features
|
40 | - Sanitization
|
41 | - Synchronous and asynchronous validation
|
42 | - Groups
|
43 | - Extensible
|
44 |
|
45 | All the features are applied through the `process` function.
|
46 |
|
47 | ```js
|
48 | Valida.process(
|
49 | @data,
|
50 | @schema,
|
51 | @callback,
|
52 | @group
|
53 | );
|
54 | ```
|
55 | **options:**
|
56 |
|
57 | * `@data` is the object to be applied the sanitization and validation
|
58 | * `@schema` is an object describing to Valida how to process it
|
59 | * `@callback` is a function that is going to be called after processing the data
|
60 | * `@group` is a string or array describing which groups must be applied in this process (optional)
|
61 |
|
62 |
|
63 | ### Sanitization
|
64 |
|
65 | Valida supports synchronous sanitization.
|
66 |
|
67 | * `toInt`
|
68 | * `toFloat`
|
69 | * `toDate`
|
70 | * `trim`
|
71 | * `string`
|
72 | * `lowerCase`
|
73 | * `titleCase`
|
74 | * `upperCaseFirst`
|
75 | * `upperCase`
|
76 | * `toBool`
|
77 |
|
78 | #### toInt
|
79 |
|
80 | **options:**
|
81 |
|
82 | * `radix` (optional, default 10)
|
83 |
|
84 | ```js
|
85 | var schema = {
|
86 | age: [{ sanitizer: Valida.Sanitizer.toInt }]
|
87 | };
|
88 | ```
|
89 |
|
90 | #### toFloat
|
91 |
|
92 | **options:**
|
93 |
|
94 | * `precision` (optional)
|
95 |
|
96 | ```js
|
97 | var schema = {
|
98 | salary: [{ sanitizer: Valida.Sanitizer.toFloat }]
|
99 | };
|
100 | ```
|
101 |
|
102 | #### toDate
|
103 |
|
104 | ```js
|
105 | var schema = {
|
106 | birthday: [{ sanitizer: Valida.Sanitizer.toDate }]
|
107 | };
|
108 | ```
|
109 |
|
110 | #### trim
|
111 |
|
112 | **options:**
|
113 |
|
114 | * `chars` (optional)
|
115 |
|
116 | ```js
|
117 |
|
118 | var schema = {
|
119 | name: [{ sanitizer: Valida.Sanitizer.trim }]
|
120 | };
|
121 | ```
|
122 |
|
123 | #### string
|
124 |
|
125 | ```js
|
126 |
|
127 | var schema = {
|
128 | name: [{ sanitizer: Valida.Sanitizer.string }]
|
129 | };
|
130 | ```
|
131 |
|
132 | #### lowerCase
|
133 |
|
134 | ```js
|
135 |
|
136 | var schema = {
|
137 | name: [{ sanitizer: Valida.Sanitizer.lowerCase }]
|
138 | };
|
139 | ```
|
140 |
|
141 | #### titleCase
|
142 |
|
143 | ```js
|
144 |
|
145 | var schema = {
|
146 | name: [{ sanitizer: Valida.Sanitizer.titleCase }]
|
147 | };
|
148 | ```
|
149 |
|
150 | #### upperCaseFirst
|
151 |
|
152 | ```js
|
153 |
|
154 | var schema = {
|
155 | name: [{ sanitizer: Valida.Sanitizer.upperCaseFirst }]
|
156 | };
|
157 | ```
|
158 |
|
159 | #### upperCase
|
160 |
|
161 | ```js
|
162 |
|
163 | var schema = {
|
164 | name: [{ sanitizer: Valida.Sanitizer.upperCase }]
|
165 | };
|
166 | ```
|
167 |
|
168 | #### toBool
|
169 |
|
170 | ```js
|
171 |
|
172 | var schema = {
|
173 | published: [{ sanitizer: Valida.Sanitizer.toBool }]
|
174 | };
|
175 | ```
|
176 |
|
177 | ### Validation
|
178 |
|
179 | Valida supports both synchronous and asynchronous validation.
|
180 |
|
181 | * `required`
|
182 | * `empty`
|
183 | * `regex`
|
184 | * `len`
|
185 | * `array`
|
186 | * `plainObject`
|
187 | * `date`
|
188 | * `integer`
|
189 | * `enum`
|
190 | * `bool`
|
191 | * `float`
|
192 | * `range`
|
193 |
|
194 | #### required
|
195 |
|
196 | Field is required.
|
197 |
|
198 | ```js
|
199 | var schema = {
|
200 | age: [{ validator: Valida.Validator.required }]
|
201 | };
|
202 | ```
|
203 |
|
204 | #### empty
|
205 |
|
206 | Field must be **not** empty.
|
207 |
|
208 | ```js
|
209 | var schema = {
|
210 | description: [{ validator: Valida.Validator.empty }]
|
211 | };
|
212 | ```
|
213 |
|
214 | #### regex
|
215 |
|
216 | Validation based in a regex.
|
217 |
|
218 | **options:**
|
219 |
|
220 | * `pattern`: regex pattern
|
221 | * `modifiers`: regex modifier (optional)
|
222 |
|
223 | ```js
|
224 | var schema = {
|
225 | name: [{ validator: Valida.Validator.regex, pattern: '[A-Z]', modifiers: 'i' }]
|
226 | };
|
227 | ```
|
228 |
|
229 | #### len
|
230 |
|
231 | Validation based in the size of an array or in the number of chars of a non-array.
|
232 |
|
233 | **options:**
|
234 |
|
235 | * `min`
|
236 | * `max`
|
237 |
|
238 | ```js
|
239 | var schema = {
|
240 | products: [{ validator: Valida.Validator.len, min: 2, max: 10 }]
|
241 | };
|
242 | ```
|
243 |
|
244 | #### array
|
245 |
|
246 | Field must be an array.
|
247 |
|
248 | ```js
|
249 | var schema = {
|
250 | products: [{ validator: Valida.Validator.array }]
|
251 | };
|
252 | ```
|
253 |
|
254 | #### plainObject
|
255 |
|
256 | Field must be a plain object.
|
257 |
|
258 | ```js
|
259 | var schema = {
|
260 | person: [{ validator: Valida.Validator.plainObject }]
|
261 | };
|
262 | ```
|
263 |
|
264 | #### date
|
265 |
|
266 | Field must be a date.
|
267 |
|
268 | ```js
|
269 | var schema = {
|
270 | createdAt: [{ validator: Valida.Validator.date }]
|
271 | };
|
272 | ```
|
273 |
|
274 | #### integer
|
275 |
|
276 | Field must be a integer.
|
277 |
|
278 | ```js
|
279 | var schema = {
|
280 | createdAt: [{ validator: Valida.Validator.integer }]
|
281 | };
|
282 | ```
|
283 |
|
284 | #### enum
|
285 |
|
286 | Field value must be list of valid values.
|
287 |
|
288 | **options:**
|
289 |
|
290 | * `items`: an array with the valid values
|
291 |
|
292 | ```js
|
293 | var schema = {
|
294 | color: [{ validator: Valida.Validator.enum, items: ['blue', 'black', 'white'] }]
|
295 | };
|
296 | ```
|
297 |
|
298 | #### bool
|
299 |
|
300 | Field must be a bool.
|
301 |
|
302 | **options:**
|
303 |
|
304 | * `default`
|
305 |
|
306 | ```js
|
307 | var schema = {
|
308 | published: [{ validator: Valida.Validator.bool, default: false }]
|
309 | };
|
310 | ```
|
311 |
|
312 | #### float
|
313 |
|
314 | Field must be a float.
|
315 |
|
316 | ```js
|
317 | var schema = {
|
318 | salary: [{ validator: Valida.Validator.float }]
|
319 | };
|
320 | ```
|
321 |
|
322 | #### range
|
323 |
|
324 | Field value must be between a min and/or max value.
|
325 |
|
326 | **options:**
|
327 |
|
328 | * `min`: The minimum value of the range
|
329 | * `max`: The maximum value of the range
|
330 |
|
331 | ```js
|
332 | var schema = {
|
333 | code: [{ validator: Valida.Validator.range, min: 0, max: 10 }]
|
334 | };
|
335 | ```
|
336 |
|
337 | ### Groups
|
338 |
|
339 | 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.
|
340 |
|
341 | ```js
|
342 | var schema = {
|
343 | id: [{ validator: Valida.Validator.required, groups: ['update'] }]
|
344 | products: [{ validator: Valida.Validator.array, groups: ['create'] }]
|
345 | };
|
346 |
|
347 | Valida.process(data, schema, function(err, ctx) {
|
348 | console.log('create', create);
|
349 | }, 'create');
|
350 | ```
|
351 |
|
352 | ### Extensible
|
353 |
|
354 | ## Contributors
|
355 | Would you like to contribute to this library? Don't be shy! [Contact me](mailto:esnunes@gmail.com) if you are interested on it.
|
356 |
|
357 | ## LICENSE
|
358 |
|
359 | (MIT License)
|
360 |
|
361 | Copyright (c) 2013 Eduardo Nunes <esnunes@gmail.com>
|
362 |
|
363 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
364 | of this software and associated documentation files (the "Software"), to deal
|
365 | in the Software without restriction, including without limitation the rights
|
366 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
367 | copies of the Software, and to permit persons to whom the Software is
|
368 | furnished to do so, subject to the following conditions:
|
369 |
|
370 | The above copyright notice and this permission notice shall be included in
|
371 | all copies or substantial portions of the Software.
|
372 |
|
373 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
374 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
375 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
376 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
377 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
378 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
379 | THE SOFTWARE.
|