Add validation support for nconf
npm install nconf-validator bash
$ curl http://npmjs.org/install.sh | sh
`
$3
` bash
$ [sudo] npm install nconf
`
$3
` bash
$ [sudo] npm install nconf-validator
`
Usage
Following is a basic usage of the plugin. See the examples directory for more usage examples.
$3
Since nconf-validator is a [nconf][0] plugin, nconf must be loaded prior to nconf-validator and its reference must be passed as a required argument. So to use nconf-validator, the code looks something like this:
`js
var nconf = require('nconf');
var nval = require('nconf-validator')(nconf);
`
$3
To add validation rules, NConfValidator#addRule() method can be used as follows:
`js
nval.addRule("app_ip", "ip");
nval.addRule("app_port", "port");
`
The above lines setup nconf-validator to perform following checks:
1. app_ip: a valid IP address
2. app_port: a valid port number
$3
Finally run validation on nval
`js
nval.validate();
`
Note that NConfValidator#validate() method is never called automatically. It must be called manually when one or more config values change and needs to be validated.
API
$3
It is the main validator class for instantiating new instance of the validator. The signature of this class is as follows:
`js
NConfValidator();
`
While instantiating you provide reference to an instance of nconf.Provider, which will be used when no provider is specified to the NConfValidator#validate() method (will be explained later). Following snippet shows how to create a new instance of NConfValidator in common scenarios:
`js
var nconf = require('nconf');
var validator = require('nconf-validator');
var config = new nconf.Provider({
// Provider configuration
});
var nval = new validator.NConfValidator(config);
// Use nval properties as described in their respective sections.
// nval.addRule( ... )
// nval.validate( ... )
`
As a convenience, you can directly call validator passing the reference to the default nconf provider.
`js
var nconf = require('nconf');
var nval = require('nconf-validator')(nconf);
// Use nval properties as described in their respective sections.
// nval.addRule( ... )
// nval.validate( ... )
`
$3
Add validation rules to the validator. The signature of this function is as follows:
`js
addRule(, );
`
* prop
It is a config property to be validated. This is specified in the same format as expected by nconf.get(). See the documentation of nconf.get() for more details.
* rule
Specifies a validation rule for the given property. You can add multiple rules for a single property by calling NConfValidator#addRule() multiple times with same prop value, in which case all the rules are validated. A rule can be one of the following:
1. A predefined format string
There are several predefined formats for validation that you can use, most of which are self-explanatory:
- any value is valid
* int - integer
* nat - positive integer (natural number)
* port - positive integer (0 - 65535)
* fqdn, domain - fully qualified domain name
* url - valid URL
* email - valid email address
* ipv4, ip, ipaddress - IPv4 addresses
* ipv6 - IPv6 addresses
* uuid - Any UUID
* uuid3, uuid4, uuid5 - UUID v3, v4, and v5, respectively
* duration - positive integer (milliseconds)
* timestamp - positive integer (Unix timestamps)
* date - date as understood by javascript Date.parse()
* isbn - international standard book number
* json, object - javascript object literal
2. An array of values
If given rule is an instance of an Array, it is considered as an enumeration of valid values. For example, the following rule checks that the value of some:prop is one of a, b, and c:
`js
someValidator.addRule('some:prop', ['a', 'b', 'c'])
`
Note that it is recommended to use only strings as array items when argv or env sources are used.
3. A built-in javascript type
If format is set to one of the built-in JavaScript constructors, Object, Array, String, Number, or Boolean, only the validation will check that the setting is of that type. For example, following rule could be added to check that the value of some:prop is a valid boolean expression (there's a reason it is called expression and not just boolean value):
`js
someValidator.addRule('some:prop', Boolean)
`
Many times, when the value is read from environment or command line, it is only available as a string. So best efforts are made to check that given expression (string representation of the object) can be transformed to an instance of the type to be checked.
Following listing shows valid expressions for each of the builtin types:
* String - Any valid string.
* Number - Any numeric value, e.g. 42, -1, 3.14
* Boolean - One of true, yes, 1, false, no, 0. The comparison is case independent.
* Object - A JSON representation.
* Array - A comma separated values (may or may not be enclosed in square brackets). Quotation marks can be used to group values, e.g. [val1, "value 2", "values 3,4, and 5"]. Note that on some platforms quotation marks are automatically removed, so you must escape quotation marks if you want to pass them to nconf-validator.
4. A user-given function
You can also provide your own format checking function. For example, following shows a custom check which passes only when value of some:prop is of length 10:
`js
someValidator.addRule('some:prop', function(x) { return x.length === 10; })
`
A custom check function receives a value to be validated and it must return truthy or falsy value to indicate whether or not value is valid.
$3
Perform validation with given rules registered with the validator. The rules are validated in the sequence they were added. The signature of this function is as follows:
`js
validate(, );
`
* conf
The conf argument must be an instance of nconf.Provider. It is optional if you've specified the value of the default nconf while creating instance of NConfValidator. However if both are specified, the conf provided to the NConfValidator#validate() method will take precedence. Note that this precedence does not form a configuration hierarchy. So if some key K is present in the config you've provided while creating instance of NConfValidator, but not in the config provided to the NConfValidator#validate() method, it'll not be present while validating.
* silent
An optional silent argument controls whether exception is thrown (if truthy) or errors are returned to the caller (if falsy). In the later case, a list of all validation errors are returned, or an empty list if there are no errors. Each item in this list is a ValidatorError object. However if silent is not given or evaluates to false, only the first validation error (again an instance of ValidatorError) is thrown.
$3
This class is used to instantiate objects which are thrown or returned from the NConfValidator#validate() method. It inherits from the builtin Error class and has following properties:
* value
The value which was validated but turned out to be invalid.
* claim
A string describing the format that was expected (e.g. "a positive integer").
* key
Name of the property which was validated.
* name
A constant string "ValidatorError" - the name of this function.
* message
A dynamic property that gives a properly formatted error message containing the above properties. This cannot be set, but you may override the ValidatorError to provide your own implementation of its properties.
If you may need this for your own purpose, the signature of this class is as follows:
`js
ValidatorError(, , );
`
where value, claim, and key are as explained above.
End Matter
$3
While comparing nconf with [convict][2], I felt both of these awesome libraries were lacking some essential features that was available in the other. nconf was very easy to extend, so I made this little nconf` plugin to add validation which was available in the other library.