joi-extender
Extends hapi joi with new top-level validation tests.
NOTE: This module relies upon and leverages special knowledge of Joi's internal structure which may change in the future and while I freely admit that this is usually a "VBI*", every effort will be made to assure it continues to work as Joi is updated.
Installation
npm install joi-extender
To build jsdoc:
npm run build
See package.json
for other script targets.
Description
joi-extender allows you to add your own "top-level" validate-able types to Joi as well as new "chainable" methods specific to the new type.
In other words, it allows you to add your own base validation types, just like joi.string()
, as well
as further chain-able tests specific to the newly created type, like joi.string().regex()
.
Example - from /examples/fiddle.js
Here's a full example, which I'll pick apart below:
(Note that while this is a very trivial example that can be easily replicated using existing joi types and validations, if we did that, we wouldn't get to use this module, would we? For a real-world example, see test/extender.js
which defines a new joi.dma()
type using is_dma.)
var util = joi = extender = ; // require('joi-extender'); var MIN_LEN = 1 // minimum acceptable length MAX_LEN = 100; // maximum acceptable length extender; extender; // ====================================== // and test it out... { var err = valerror ? valerror : 'no error'; //console.log(util.inspect(val,{depth:null})); console;} var result; result = joi;;// => {error: '"value" is required', value: undefined } result = joi;;// => {error: '"value" must be a string', value: 1 } result = joi;;// => {error:'"value" must be >= 1 and <= 100 chars in length', value: '' } result = joilabel'range value';;// => {error:'range value "1" must be between 10 and 20 chars in length', value: '1' } result = joi;;// => {error: null, value: 'bar' } result = joilabel'name';;// => {error: '"bar" is not an allowed value for "name"', value: 'bar' } result = joi;;// => {error: '"value" must be uppercase', value: 'foo' } result = joi;;// => {error: null, value: 'FOO' }
So, how does this work?
First, we need to create a new validator which we will be able to call as joi.fiddle()
:
// create a new Joi validation "top-level" validation function called "fiddle"
extender.addValidator('fiddle',{
Note that the first argument is the name of the validator type we want to create, and is used to add a new property to the joi object and to report errors correctly.
Next, we can add "requirements" tests that will all be called when our validator is first invoked. Tests defined here should return true if the value passes validation and will report the error defined below under the same key as the test. (See errmsgs
below.)
One possible use for these tests would be to assure the value is a native JS type, such as a String.
requirements: // Let's assure we're working with a string: { return 'string'===typeof val; } // and that it's the right size: { return vallength >= MIN_LEN && vallength <= MAX_LEN; }
Next, we can add further optional validation tests that become our new "chainables" and are specific to our new validation type, like .required()
or .length(limit)
. These tests should return null
on success or the key of the appropriate errmsg to display on failure as defined below.
tests: // tests whether the value is composed of only uppercase letters // if the test fails, return 'uppercase' to access the error message defined below { return val ? null : 'uppercase'; } // tests whether the value is within an expected range // if the test fails, return 'range' { if !Array && argslength === 2 throw 'joi.fiddle().range() requires two numeric arguments'; if!'number' === typeof args0 && 'number' === typeof args1 throw 'joi.fiddle().range() requires two numeric arguments'; return vallength >= args0 && vallength <= args1 ? null : 'range'; } // tests whether the value is not allowed // if the test fails, return 'not_allowed' to access the error message defined below { if !Array && 'string' === typeof args0 throw 'joi.fiddle().disallow() requires one string argument'; return val === args0 ? 'disallowed' : null; }
Finally, we add useful error messages which will be reported on validation failure.
errmsgs: 'base': 'must be a string' 'len': 'must be >= ' + MIN_LEN + ' and <= ' + MAX_LEN + ' chars in length' 'range': '{{key}} "{{value}}" must be between {{args.0}} and {{args.1}} chars in length' 'uppercase': 'must be uppercase' 'disallowed': '"{{value}}" is not an allowed value for "{{key}}"' });
Ok, now we have a new validator but Joi has no idea how to use it, so we need to register it with Joi.
extender;
Now, we can use joi.fiddle()
with .isUpperCase()
, range(n:number,m:number)
and .disallow(target:string)
in our validations.
* Very Bad Idea.