joi 4.6.2 → 4.9.0

package/README.md

@@ -2,20 +2,20 @@
 
 Object schema description language and validator for JavaScript objects.
 
-Current version: **4.6.x**
+Current version: **4.7.x**
 
 [![Build Status](https://secure.travis-ci.org/hapijs/joi.png)](http://travis-ci.org/hapijs/joi)
 
-Lead Maintainer: [Eran Hammer](https://github.com/hueniverse)
+Lead Maintainer: [Nicolas Morel](https://github.com/marsup)
 
 ## Table of Contents
 
 <img src="https://raw.github.com/hapijs/joi/master/images/validation.png" align="right" />
 - [Example](#example)
 - [Usage](#usage)
-    - [`validate(value, schema, [options], callback)`](#validatevalue-schema-options-callback)
+    - [`validate(value, schema, [options], [callback])`](#validatevalue-schema-options-callback)
     - [`compile(schema)`](#compileschema)
-    - [`assert(value, schema)`](#assertvalue-schema)
+    - [`assert(value, schema, [message])`](#assertvalue-schema-message)
     - [`any`](#any)
         - [`any.allow(value)`](#anyallowvalue)
         - [`any.valid(value)`](#anyvalidvalue)
@@ -34,12 +34,14 @@ Lead Maintainer: [Eran Hammer](https://github.com/hueniverse)
         - [`any.default(value)`](#anydefaultvalue)
         - [`any.concat(schema)`](#anyconcatschema)
         - [`any.when(ref, options)`](#anywhenref-options)
+        - [`any.label(name)`](#anylabelname)
     - [`array`](#array)
         - [`array.includes(type)`](#arrayincludestype)
         - [`array.excludes(type)`](#arrayexcludestype)
         - [`array.min(limit)`](#arrayminlimit)
         - [`array.max(limit)`](#arraymaxlimit)
         - [`array.length(limit)`](#arraylengthlimit)
+        - [`array.unique()`](#arrayunique)
     - [`binary`](#binary)
       - [`binary.encoding(encoding)`](#binaryencodingencoding)
       - [`binary.min(limit)`](#binaryminlimit)
@@ -49,11 +51,16 @@ Lead Maintainer: [Eran Hammer](https://github.com/hueniverse)
     - [`date`](#date)
         - [`date.min(date)`](#datemindate)
         - [`date.max(date)`](#datemaxdate)
+        - [`date.format(format)`](#dateformatformat)
+        - [`date.iso()`](#dateiso)
     - [`func`](#func)
     - [`number`](#number)
         - [`number.min(limit)`](#numberminlimit)
         - [`number.max(limit)`](#numbermaxlimit)
+        - [`number.greater(limit)`](#numbergreaterlimit)
+        - [`number.less(limit)`](#numberlesslimit)
         - [`number.integer()`](#numberinteger)
+        - [`number.precision(limit)`](#numberprecisionlimit)
     - [`object`](#object)
         - [`object.keys([schema])`](#objectkeysschema)
         - [`object.min(limit)`](#objectminlimit)
@@ -61,24 +68,26 @@ Lead Maintainer: [Eran Hammer](https://github.com/hueniverse)
         - [`object.length(limit)`](#objectlengthlimit)
         - [`object.pattern(regex, schema)`](#objectpatternregex-schema)
         - [`object.and(peers)`](#objectandpeers)
+        - [`object.nand(peers)`](#objectnandpeers)
         - [`object.or(peers)`](#objectorpeers)
         - [`object.xor(peers)`](#objectxorpeers)
         - [`object.with(key, peers)`](#objectwithkey-peers)
         - [`object.without(key, peers)`](#objectwithoutkey-peers)
         - [`object.rename(from, to, [options])`](#objectrenamefrom-to-options)
-        - [`object.assert(ref, schema, message)`](#objectassertref-schema-message)
+        - [`object.assert(ref, schema, [message])`](#objectassertref-schema-message)
         - [`object.unknown([allow])`](#objectunknownallow)
+        - [`object.type(constructor, [name])`](#objecttypeconstructorname)
     - [`string`](#string)
         - [`string.insensitive()`](#stringinsensitive)
         - [`string.min(limit, [encoding])`](#stringminlimit-encoding)
         - [`string.max(limit, [encoding])`](#stringmaxlimit-encoding)
+        - [`string.creditCard()`](#stringcreditCard)
         - [`string.length(limit, [encoding])`](#stringlengthlimit-encoding)
-        - [`string.regex(pattern)`](#stringregexpattern)
+        - [`string.regex(pattern, [name])`](#stringregexpattern)
         - [`string.alphanum()`](#stringalphanum)
         - [`string.token()`](#stringtoken)
         - [`string.email()`](#stringemail)
         - [`string.guid()`](#stringguid)
-        - [`string.isoDate()`](#stringisodate)
         - [`string.hostname()`](#stringhostname)
         - [`string.lowercase()`](#stringlowercase)
         - [`string.uppercase()`](#stringuppercase)
@@ -162,7 +171,7 @@ When validating a schema:
 * Strings are utf-8 encoded by default.
 * Rules are defined in an additive fashion and evaluated in order after whitelist and blacklist checks.
 
-### `validate(value, schema, [options], callback)`
+### `validate(value, schema, [options], [callback])`
 
 Validates a value using the given schema and options where:
 - `value` - the value being validated.
@@ -173,13 +182,16 @@ Validates a value using the given schema and options where:
   - `allowUnknown` - when `true`, allows object to contain unknown keys which are ignored. Defaults to `false`.
   - `skipFunctions` - when `true`, ignores unknown keys with a function value. Defaults to `false`.
   - `stripUnknown` - when `true`, unknown keys are deleted (only when value is an object). Defaults to `false`.
-  - `language` - overrides individual error messages. Defaults to no override (`{}`).
+  - `language` - overrides individual error messages, when `'label'` is set, it overrides the key name in the error message. Defaults to no override (`{}`).
+  - `presence` - sets the default presence requirements. Supported modes: `'optional'`, `'required'`, and `'forbidden'`.
+    Defaults to `'optional'`.
   - `context` - provides an external data set to be used in [references](#refkey-options). Can only be set as an external option to
     `validate()` and not using `any.options()`.
-- `callback` - the synchronous callback method using the signature `function(err, value)` where:
+- `callback` - the optional synchronous callback method using the signature `function(err, value)` where:
   - `err` - if validation failed, the error reason, otherwise `null`.
   - `value` - the validated value with any type conversions and other modifiers applied (the input is left unchanged). `value` can be
-    incomplete if validation failed and `abortEarly` is `true`.
+    incomplete if validation failed and `abortEarly` is `true`. If callback is not provided, then returns an object with error
+    and value properties.
 
 ```javascript
 var schema = {
@@ -193,6 +205,11 @@ var value = {
 Joi.validate(value, schema, function (err, value) { });
 // err -> null
 // value.a -> 123 (number, not string)
+
+// or
+var result = Joi.validate(value, schema);
+// result.error -> null
+// result.value -> { "a" : 123 }
 ```
 
 ### `compile(schema)`
@@ -219,11 +236,12 @@ var schema = Joi.alternatives().try([
 ]);
 ```
 
-### `assert(value, schema)`
+### `assert(value, schema, [message])`
 
 Validates a value against a schema and throws if validation fails where:
 - `value` - the value to validate.
 - `schema` - the schema object.
+- `message` - optional message sting prefix added in front of the error message.
 
 ```javascript
 Joi.assert('x', Joi.number());
@@ -302,7 +320,7 @@ Marks a key as forbidden which will not allow any value except `undefined`. Used
 
 ```javascript
 var schema = {
-    a: Joi.any.forbidden()
+    a: Joi.any().forbidden()
 };
 ```
 
@@ -422,6 +440,27 @@ var schema = {
 };
 ```
 
+Alternatively, if you want to specify a specific type such as `string`, `array`, etc, you can do so like this:
+
+```javascript
+var schema = {
+    a: Joi.valid('a', 'b', 'other'),
+    other: Joi.string()
+        .when('a', { is: 'other', then: Joi.required() }),
+};
+```
+
+#### `any.label(name)`
+
+Overrides the key name in error messages.
+- `name` - the name of the key.
+
+```javascript
+var schema = {
+    first_name: Joi.string().label('First Name')
+};
+```
+
 ### `array`
 
 Generates a schema object that matches an array data type.
@@ -478,6 +517,14 @@ Specifies the exact number of items in the array where:
 var schema = Joi.array().length(5);
 ```
 
+#### `array.unique()`
+
+Requires the array values to be unique. Only works for literals (numbers and strings), all other types are ignored.
+
+```javascript
+var schema = Joi.array().unique();
+```
+
 ### `boolean`
 
 Generates a schema object that matches a boolean data type (as well as the strings 'true', 'false', 'yes', and 'no'). Can also be called via `bool()`.
@@ -555,6 +602,12 @@ Specifies the oldest date allowed where:
 var schema = Joi.date().min('1-1-1974');
 ```
 
+Note: `'now'` can be passed in lieu of `date` so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future.
+
+```javascript
+var schema = Joi.date().min('now');
+```
+
 #### `date.max(date)`
 
 Specifies the latest date allowed where:
@@ -564,6 +617,29 @@ Specifies the latest date allowed where:
 var schema = Joi.date().max('12-31-2020');
 ```
 
+Note: `'now'` can be passed in lieu of `date` so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future.
+
+```javascript
+var schema = Joi.date().max('now');
+```
+
+#### `date.format(format)`
+
+Specifies the allowed date format:
+- `format` - string or array of strings that follow the `moment.js` [format](http://momentjs.com/docs/#/parsing/string-format/).
+
+```javascript
+var schema = Joi.date().format('YYYY/MM/DD');
+```
+
+#### `date.iso()`
+
+Requires the string value to be in valid ISO 8601 date format.
+
+```javascript
+var schema = Joi.date().iso();
+```
+
 ### `func`
 
 Generates a schema object that matches a function type.
@@ -604,6 +680,22 @@ Specifies the maximum value where:
 var schema = Joi.number().max(10);
 ```
 
+#### `number.greater(limit)`
+
+Specifies that the value must be greater than `limit`.
+
+```javascript
+var schema = Joi.number().greater(5);
+```
+
+#### `number.less(limit)`
+
+Specifies that the value must be less than `limit`.
+
+```javascript
+var schema = Joi.number().less(10);
+```
+
 #### `number.integer()`
 
 Requires the number to be an integer (no floating point).
@@ -612,6 +704,15 @@ Requires the number to be an integer (no floating point).
 var schema = Joi.number().integer();
 ```
 
+#### `number.precision(limit)`
+
+Specifies the maximum number of decimal places where:
+- `limit` - the maximum number of decimal places allowed.
+
+```javascript
+var schema = Joi.number().precision(2);
+```
+
 ### `object`
 
 Generates a schema object that matches an object data type (as well as JSON strings that parsed into objects). Defaults
@@ -630,17 +731,21 @@ object.validate({ a: 5 }, function (err, value) { });
 
 #### `object.keys([schema])`
 
-Sets the allowed object keys where:
-- `schema` - optional object where each key is assinged a **joi** type object. If `schema` is `{}` no keys allowed.
+Sets or extends the allowed object keys where:
+- `schema` - optional object where each key is assigned a **joi** type object. If `schema` is `{}` no keys allowed.
   If `schema` is `null` or `undefined`, any key allowed. If `schema` is an object with keys, the keys are added to any
   previously defined keys (but narrows the selection if all keys previously allowed). Defaults to 'undefined' which
   allows any child key.
 
 ```javascript
-var object = Joi.object().keys({
-    a: Joi.number()
+var base = Joi.object().keys({
+    a: Joi.number(),
     b: Joi.string()
 });
+// Validate keys a, b and c.
+var extended = base.keys({
+    c: Joi.boolean()
+});
 ```
 
 #### `object.min(limit)`
@@ -696,6 +801,20 @@ var schema = Joi.object().keys({
 }).and('a', 'b');
 ```
 
+#### `object.nand(peers)`
+
+Defines a relationship between keys where not all peers can be present at the
+same time where:
+- `peers` - the key names of which if one present, the others may not all be present. `peers` can be a single string value, an
+  array of string values, or each peer provided as an argument.
+
+```javascript
+var schema = Joi.object().keys({
+    a: Joi.any(),
+    b: Joi.any()
+}).nand('a', 'b');
+```
+
 #### `object.or(peers)`
 
 Defines a relationship between keys where one of the peers is required (and more than one is allowed) where:
@@ -771,13 +890,13 @@ var object = Joi.object().keys({
 object.validate({ b: 5 }, function (err, value) { });
 ```
 
-#### `object.assert(ref, schema, message)`
+#### `object.assert(ref, schema, [message])`
 
 Verifies an assertion where:
 - `ref` - the key name or [reference](#refkey-options).
 - `schema` - the validation rules required to satisfy the assertion. If the `schema` includes references, they are resolved against
   the object value, not the value of the `ref` target.
-- `message` - human-readable message used when the assertion fails.
+- `message` - optional human-readable message used when the assertion fails. Defaults to 'failed to pass the assertion test'.
 
 ```javascript
 var schema = Joi.object().keys({
@@ -800,6 +919,16 @@ Overrides the handling of unknown keys for the scope of the current object only
 var schema = Joi.object({ a: Joi.any() }).unknown();
 ```
 
+#### `object.type(constructor, [name])`
+
+Requires the object to be an instance of a given constructor where:
+- `constructor` - the constructor function that the object must be an instance of.
+- `name` - an alternate name to use in validation errors. This is useful when the constructor function does not have a name.
+
+```javascript
+var schema = Joi.object().type(RegExp);
+```
+
 ### `string`
 
 Generates a schema object that matches a string data type. Note that empty strings are not allowed by default and must be enabled with `allow('')`.
@@ -839,6 +968,15 @@ Specifies the maximum number of string characters where:
 var schema = Joi.string().max(10);
 ```
 
+#### `string.creditCard()`
+
+Requires the number to be a credit card number (Using [Lunh
+Algorithm](http://en.wikipedia.org/wiki/Luhn_algorithm)).
+
+```javascript
+var schema = Joi.string().creditCard();
+```
+
 #### `string.length(limit, [encoding])`
 
 Specifies the exact string length required where:
@@ -849,10 +987,11 @@ Specifies the exact string length required where:
 var schema = Joi.string().length(5);
 ```
 
-#### `string.regex(pattern)`
+#### `string.regex(pattern, [name])`
 
 Defines a regular expression rule where:
 - `pattern` - a regular expression object the string value must match against.
+- `name` - optional name for patterns (useful with multiple patterns). Defaults to 'required'.
 
 ```javascript
 var schema = Joi.string().regex(/^[abc]+$/);
@@ -890,14 +1029,6 @@ Requires the string value to be a valid GUID.
 var schema = Joi.string().guid();
 ```
 
-#### `string.isoDate()`
-
-Requires the string value to be in valid ISO 8601 date format.
-
-```javascript
-var schema = Joi.string().isoDate();
-```
-
 #### `string.hostname()`
 
 Requires the string value to be a valid hostname as per [RFC1123](http://tools.ietf.org/html/rfc1123).
@@ -947,7 +1078,7 @@ var alt = Joi.alternatives().try(Joi.number(), Joi.string());
 // Same as [Joi.number(), Joi.string()]
 ```
 
-#### `alternatives.try(schemas)``
+#### `alternatives.try(schemas)`
 
 Adds an alternative schema type for attempting to match against the validated value where:
 - `schema` - an array of alternative **joi** types. Also supports providing each type as a separate argument.
@@ -1003,8 +1134,8 @@ var schema = {
 Generates a reference to the value of the named key. References are resolved at validation time and in order of dependency
 so that if one key validation depends on another, the dependent key is validated second after the reference is validated.
 References support the following arguments:
-- `key` - the reference target. References cannot point up the object tree, only to siebling keys, but they can point to
-  their siebling's children (e.g. 'a.b.c') using the `.` separator. If a `key` starts with `$` is signifies a context reference
+- `key` - the reference target. References cannot point up the object tree, only to sibling keys, but they can point to
+  their siblings' children (e.g. 'a.b.c') using the `.` separator. If a `key` starts with `$` is signifies a context reference
   which is looked up in the `context` option object.
 - `options` - optional settings:
     - `separator` - overrides the default `.` hierarchy separator.

package/examples/conditionalRequire.js

@@ -0,0 +1,43 @@
+// This is an example of a survey to obtain the reputation of Parisians
+// It contains examples of how to conditionally require keys based on values of other keys
+
+var Joi = require("../");
+
+// This is a valid value for integer rating 1 - 5
+var intRating = Joi.number().integer().min(1).max(5);
+
+var schema = Joi.object().keys({ 
+    // Do you know any French people? yes or no (required)
+    q1: Joi.boolean().required(),
+    // Do you know any Parisians? yes or no (required if answered yes in q1)
+    q2: Joi.boolean()
+        .when('q1', { is: true, then: Joi.required() }),
+    // How many french in paris do you know? 1-6, 6-10, 11-50 or 50+ (required if answered yes in q2)
+    q3: Joi.string()
+        .when('q2', { is: true, then: Joi.valid('1-5', '6-10', '11-50', '50+').required() }),
+    // Rate 20% of most friendly Parisians, from how many people you know answered in q3, individually on 1-5 rating
+    q4: Joi.array()
+        .when('q3', {is: '1-5', then: Joi.array().min(0).max(1).includes(intRating).required() })
+        .when('q3', {is: '6-10', then: Joi.array().min(1).max(2).includes(intRating).required() })
+        .when('q3', {is: '11-50', then: Joi.array().min(2).max(10).includes(intRating).required() })
+        .when('q3', {is: '50+' , then: Joi.array().min(10).includes(intRating).required() }),
+    // Rate remaining 80% of Parisians, from how many people you know answered in q3, individually on 1-5 rating
+    q5: Joi.array()
+        .when('q3', {is: '1-5', then: Joi.array().min(1).max(4).includes(intRating).required() })
+        .when('q3', {is: '6-10', then: Joi.array().min(4).max(8).includes(intRating).required() })
+        .when('q3', {is: '11-50', then: Joi.array().min(8).max(40).includes(intRating).required() })
+        .when('q3', {is: '50+' , then: Joi.array().min(40).includes(intRating).required().required() }),
+    // Rate the reputation of Parisians in general, 1-5 rating
+    q6: intRating.required()    
+});
+
+var response = {
+	q1: true,
+	q2: true,
+	q3: '1-5',
+	q4: [5],
+	q4: [1],
+	q6: 2
+};
+
+Joi.assert(response, schema);

package/examples/customMessage.js

@@ -0,0 +1,22 @@
+var Joi = require('../');
+
+
+var schema = Joi.object().options({ abortEarly: false }).keys({
+    email: Joi.string().email().required().label('User Email'),
+    password: Joi.string().min(8).required(),
+    password_confirmation: Joi.any().valid(Joi.ref('password')).required().options({ language: { any: { allowOnly: 'must match password' }, label: 'Password Confirmation' } }).label('This label is not used because language.label takes precedence'),
+    first_name: Joi.string().required(),
+    last_name: Joi.string().required(),
+    company: Joi.string().optional()
+});
+
+
+var data = {
+    email: 'not_a_valid_email_to_show_custom_label',
+    password: 'abcd1234',
+    password_confirmation: 'abc1',
+    first_name: 'Joe',
+    last_name: 'Doe'
+};
+
+Joi.assert(data, schema);

package/examples/multipleWhen.js

@@ -0,0 +1,17 @@
+var Joi = require('../');
+
+
+var schema = {
+    type: Joi.string().required(),
+    subtype: Joi.alternatives()
+        .when('type', {is: 'video', then: Joi.valid('mp4', 'wav')})
+        .when('type', {is: 'audio', then: Joi.valid('mp3')})
+        .when('type', {is: 'image', then: Joi.valid('jpg', 'png')})
+        .when('type', {is: 'pdf'  , then: Joi.valid('document')})
+};
+
+
+Joi.assert({ type: 'video', subtype: 'mp4' }, schema); // Pass
+Joi.assert({ type: 'video', subtype: 'wav' }, schema); // Pass
+Joi.assert({ type: 'other', subtype: 'something' }, schema); // Fail
+Joi.assert({ type: 'audio', subtype: 'mp4' }, schema); // Fail

package/lib/any.js

@@ -19,7 +19,8 @@ internals.defaults = {
     allowUnknown: false,
     skipFunctions: false,
     stripUnknown: false,
-    language: {}
+    language: {},
+    presence: 'optional'
     // context: null
 };
 
@@ -43,7 +44,7 @@ module.exports = internals.Any = function () {
         insensitive: false,
         trim: false,
         case: undefined                         // upper, lower
-    */};
+    */ };
 
     this._description = null;
     this._unit = null;
@@ -61,8 +62,7 @@ internals.Any.prototype.isImmutable = true;     // Prevents Hoek from deep cloni
 
 internals.Any.prototype.clone = function () {
 
-    var obj = {};
-    obj.__proto__ = Object.getPrototypeOf(this);
+    var obj = Object.create(Object.getPrototypeOf(this));
 
     obj.isJoi = true;
     obj._type = this._type;
@@ -207,24 +207,24 @@ internals.Any.prototype.required = internals.Any.prototype.exist = function () {
 internals.Any.prototype.optional = function () {
 
     var obj = this.clone();
-    delete obj._flags.presence;     // Defaults to 'optional'
+    obj._flags.presence = 'optional';
     return obj;
 };
 
 
-internals.Any.prototype.default = function (value) {
+internals.Any.prototype.forbidden = function () {
 
     var obj = this.clone();
-    obj._flags.default = value;
-    Ref.push(obj._refs, value);
+    obj._flags.presence = 'forbidden';
     return obj;
 };
 
 
-internals.Any.prototype.forbidden = function () {
+internals.Any.prototype.default = function (value) {
 
     var obj = this.clone();
-    obj._flags.presence = 'forbidden';
+    obj._flags.default = value;
+    Ref.push(obj._refs, value);
     return obj;
 };
 
@@ -329,26 +329,25 @@ internals.Any.prototype._validate = function (value, state, options, reference)
 
     // Check presence requirements
 
-    if (this._flags.presence) {                         // 'required', 'forbidden', or 'ignore'
-        if (this._flags.presence === 'required' &&
-            value === undefined) {
-
-            errors.push(Errors.create('any.required', null, state, options));
+    var presence = this._flags.presence || options.presence;
+    if (presence === 'optional') {
+        if (value === undefined) {
             return finish();
         }
-        else if (this._flags.presence === 'forbidden') {
-            if (value === undefined) {
-                return finish();
-            }
+    }
+    else if (presence === 'required' &&
+            value === undefined) {
 
-            errors.push(Errors.create('any.unknown', null, state, options));
-            return finish();
-        }
+        errors.push(Errors.create('any.required', null, state, options));
+        return finish();
     }
-    else {                                              // 'optional'
+    else if (presence === 'forbidden') {
         if (value === undefined) {
             return finish();
         }
+
+        errors.push(Errors.create('any.unknown', null, state, options));
+        return finish();
     }
 
     // Check allowed and denied values using the original value
@@ -496,7 +495,7 @@ internals.Any.prototype.describe = function () {
     for (var i = 0, il = this._tests.length; i < il; ++i) {
         var validator = this._tests[i];
         var item = { name: validator.name };
-        if (validator.arg) {
+        if (validator.arg !== void 0) {
             item.arg = validator.arg;
         }
         description.rules.push(item);
@@ -509,6 +508,18 @@ internals.Any.prototype.describe = function () {
     return description;
 };
 
+internals.Any.prototype.label = function (name) {
+
+    Hoek.assert(name && typeof name === 'string', 'Label name must be a non-empty string');
+
+    var obj = this.clone();
+    var options = { language: { label: name } };
+    
+    // If language.label is set, it should override this label
+    obj._settings = internals.concatSettings(options, obj._settings);
+    return obj;
+};
+
 
 // Set
 

package/lib/array.js

@@ -189,4 +189,29 @@ internals.Array.prototype.length = function (limit) {
 };
 
 
+internals.Array.prototype.unique = function () {
+
+    return this._test('unique', undefined, function (value, state, options) {
+
+        var found = {
+            string: {},
+            number: {}
+        };
+
+        for (var i = 0, il = value.length; i < il; ++i) {
+            var item = value[i];
+            var type = typeof item;
+            var records = found[type];
+            if (records) {
+                if (records[item]) {
+                    return Errors.create('array.unique', { pos: i }, state, options);
+                }
+
+                records[item] = true;
+            }
+        }
+    });
+};
+
+
 module.exports = new internals.Array();