tsa
Guard your REST API with a bit of fascism.
TSA is a node.js library designed to take JSON input and:
- filter it against a whitelist
- validate it
- transform it
- provide default values
It has been designed with usage in an Express-based JSON REST API in mind, and allows you to easily pass it into your route as middleware.
Table of Contents
- Installation
- Usage
- Usage : Using TSA Directly
- Usage : Using TSA via Express Middleware
- Creating Guards
- Creating Guards : Nested Guards
- Creating Guards : Required Properties
- Creating Guards : Optional Properties
- Creating Guards : Whitelisting
- Creating Guards : Default Values
- Creating Guards : Built-In Validations
- Creating Guards : Custom Validations
- Creating Guards : Transformations
- Creating Guards : Sanitization
- Creating Guards : Rename Properties
- Creating Guards : Combinations
- Creating Guards : Error Handling
- Test
- License
- Author
Installation
$ npm install tsa
Usage
Using TSA Directly
Create a guard:
var tsa = ;var guard = ;
Validate input against guard:
var input = property1: 'foo' property4: 'bar';;
Using TSA via Express Middleware
Create a guard:
var tsa = ;var guard = ;
Ensure you're using express's body parser:
app;
Add that guard's middleware to your route:
app; app;
Alternatively you can handle the errors on a per-route basis instead of globally:
app;
Creating Guards
Nested Guards
var address = ;var person = ;
Nested guards can also be created inline:
var person = ;
You can validate/transform/etc nested guards either at the definition level, or the usage level:
// example of adding validations to guard definitionvar address = ;
// example of adding validations to guard usagevar person = ;
Required Properties
var guard = ;var input = {};;
You can provide a custom error message like so:
var guard = ;
Optional Properties
var guard = ;var input = {};;
Whitelisting
var guard = ;var input = property1: 'foo' property2: 'bar';;
Default Values
var guard = ;var input = {};;
Optionally, the default value can be a function which will be executed by tsa:
var { return ;};var guard = ;var input = {};;
Built-In Validations
TSA ships with a few validations built-in. Here are some examples:
var guard = ;
var guard = ;
var guard = ;
Custom Validations
var { ifinput === input ; // yes, this is uppercase else ; // oh noes! };var guard = ;var input = foo: 'bar' ;;
Your custom validations can return multiple errors, if necessary:
var { if... ; // passed! else ; // failed... };
Transformations
var { ;};var guard = ;var input = foo: 'bar' ;;
Sanitization
Sanitizing a property runs a validation function against it, but rather than failing the guard if an error is reported that property is simply thrown away in the case of an error:
var { ifinput === input ; // yes, this is uppercase else ; // oh noes! };var guard = ;var input = foo: 'bar' fizz: 'BANG' ;;
Note that you can run TSA's built-in validations through sanitize:
var guard = ;
Rename Properties
var guard = ;var input = foo: 'blah' ;;
Combinations
You can combine any and all of the above like so:
var { ;};var guard = ;var input = foo: 'bar' ;;
Error Handling
Errors for nested structures are returned like so:
key: 'first' error: 'Required property not provided.' key: 'address' error: key: 'street1' error: 'Required property not provided.' key: 'zip' error: 'Required property not provided.'
While this is a very structured format, it isn't always the easiest for
doing things like highlighting form fields that have errors. In those
situations you can pass the error structure into the tsa.flattenErrors
method to get back something like this:
key: 'first' error: 'Required property not provided.' key: 'address[street1]' error: 'Required property not provided.' key: 'address[zip]' error: 'Required property not provided.'
Passing {hash: true}
into tsa.flattenErrors
as the second argument results in:
'first': 'Required property not provided.' 'address[street1]': 'Required property not provided.' 'address[zip]': 'Required property not provided.'
Test
Run tests via mocha:
$ npm install -g mocha$ git clone git://github.com/TroyGoode/node-tsa.git tsa$ cd tsa/$ npm install$ mocha
Run example web app:
$ git clone git://github.com/TroyGoode/node-tsa.git tsa$ cd tsa/$ npm install$ cd example/$ npm install$ npm start$ open http://localhost:3000