nconf-validator v0.0.3
nconf-validator
Validation plugin for nconf
Installation
Installing npm (node package manager)
$ curl http://npmjs.org/install.sh | sh
Installing nconf
$ [sudo] npm install nconf
Installing nconf-validator
$ [sudo] npm install nconf-validator
Usage
Following is a basic usage of the plugin. See the examples
directory for more usage examples.
Require
Since nconf-validator
is a nconf
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:
var nconf = require('nconf');
var nval = require('nconf-validator')(nconf);
Add rules
To add validation rules, NConfValidator#addRule()
method can be used as follows:
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
Validate
Finally run validation on nval
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
NConfValidator
It is the main validator class for instantiating new instance of the validator. The signature of this class is as follows:
NConfValidator(<config?>);
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:
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.
var nconf = require('nconf');
var nval = require('nconf-validator')(nconf);
// Use `nval` properties as described in their respective sections.
// `nval.addRule( ... )`
// `nval.validate( ... )`
NConfValidator#addRule()
Add validation rules to the validator. The signature of this function is as follows:
addRule(<prop>, <rule>);
prop
It is a config property to be validated. This is specified in the same format as expected bynconf.get()
. See the documentation ofnconf.get()
for more details.rule
Specifies a validation rule for the given property. You can add multiple rules for a single property by callingNConfValidator#addRule()
multiple times with sameprop
value, in which case all the rules are validated. A rule can be one of the following:- A predefined format string There are several predefined formats for validation that you can use, most of which are self-explanatory:
*
- any value is validint
- integernat
- positive integer (natural number)port
- positive integer (0 - 65535)fqdn
,domain
- fully qualified domain nameurl
- valid URLemail
- valid email addressipv4
,ip
,ipaddress
- IPv4 addressesipv6
- IPv6 addressesuuid
- Any UUIDuuid3
,uuid4
,uuid5
- UUID v3, v4, and v5, respectivelyduration
- positive integer (milliseconds)timestamp
- positive integer (Unix timestamps)date
- date as understood by javascriptDate.parse()
isbn
- international standard book numberjson
,object
- javascript object literal
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 ofa
,b
, andc
:someValidator.addRule('some:prop', ['a', 'b', 'c'])
Note that it is recommended to use only strings as array items when
argv
orenv
sources are used.A built-in javascript type If
format
is set to one of the built-in JavaScript constructors,Object
,Array
,String
,Number
, orBoolean
, only the validation will check that the setting is of that type. For example, following rule could be added to check that the value ofsome:prop
is a valid boolean expression (there's a reason it is called expression and not just boolean value):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.14Boolean
- One oftrue
,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 tonconf-validator
.
- 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:
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.someValidator.addRule('some:prop', function(x) { return x.length === 10; })
NConfValidator#validate()
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:
validate(<conf?>, <silent?>);
conf
Theconf
argument must be an instance ofnconf.Provider
. It is optional if you've specified the value of the defaultnconf
while creating instance ofNConfValidator
. However if both are specified, theconf
provided to theNConfValidator#validate()
method will take precedence. Note that this precedence does not form a configuration hierarchy. So if some keyK
is present in the config you've provided while creating instance ofNConfValidator
, but not in the config provided to theNConfValidator#validate()
method, it'll not be present while validating.silent
An optionalsilent
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 aValidatorError
object. However ifsilent
is not given or evaluates tofalse
, only the first validation error (again an instance ofValidatorError
) is thrown.
ValidatorError
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 theValidatorError
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:
ValidatorError(<value>, <claim>, <key?>);
where value
, claim
, and key
are as explained above.
End Matter
Afterword
While comparing nconf
with convict
, 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.